# Was ist ein Widget?

Source: https://www.arc-rider.com/docs/intro/was-sind-widgets


<!-- host:react -->
# Was ist ein Widget in React?

Ein arcWidget ist eine konfigurierbare Komponente für eine Geschäftsanwendung: zum Beispiel eine Tabelle, ein Kalender oder ein Kanban-Board. Du übergibst die Darstellung als `data` und verbindest Ereignisse über Callback-Props mit deiner Anwendung.

## Ein vollständiges Beispiel

```tsx
import {
  ArcWidgetBadge,
  ArcWidgetIcon,
  ArcWidgetKpiBar,
  ArcWidgetProgressBar,
  ArcWidgetTable,
  type ArcWidgetTableData,
  type ArcWidgetTableRow,
} from '@arcrider/arcwidgets-react';
import { useMemo, useState, type CSSProperties } from 'react';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';

type Theme = 'light' | 'dark';
type DbStatus = 'Active' | 'Idle' | 'Locked';
type DbRow = {
  id: string;
  schema: string;
  name: string;
  type: 'Table' | 'View';
  rows: number;
  size: string;
  status: DbStatus;
};

const STATUS_LOOK: Record<
  DbStatus,
  { fontColor: string; backgroundColor: string }
> = {
  Active: { fontColor: '#15803D', backgroundColor: '#DCFCE7' },
  Idle: { fontColor: '#52525B', backgroundColor: '#F4F4F5' },
  Locked: { fontColor: '#991B1B', backgroundColor: '#FFE4E6' },
};
const STATUS_LOOK_DARK: Record<
  DbStatus,
  { fontColor: string; backgroundColor: string }
> = {
  Active: { fontColor: '#86EFAC', backgroundColor: '#14532D' },
  Idle: { fontColor: '#A1A1AA', backgroundColor: '#27272A' },
  Locked: { fontColor: '#FDA4AF', backgroundColor: '#4C0519' },
};

const SCHEMA_THEME = {
  public: {
    light: { bg: '#E8F1FF', ink: '#2563EB', track: '#BFDBFE' },
    dark: { bg: '#152033', ink: '#93C5FD', track: '#1E3A5F' },
  },
  auth: {
    light: { bg: '#FFF4E8', ink: '#C2410C', track: '#FED7AA' },
    dark: { bg: '#24180E', ink: '#FDBA74', track: '#4A2E12' },
  },
  storage: {
    light: { bg: '#E8F8EF', ink: '#15803D', track: '#BBF7D0' },
    dark: { bg: '#122018', ink: '#86EFAC', track: '#14532D' },
  },
} as const;
type SchemaName = keyof typeof SCHEMA_THEME;
const SCHEMAS = Object.keys(SCHEMA_THEME) as SchemaName[];
const STATUSES: DbStatus[] = ['Active', 'Idle', 'Locked'];

const demoRows: DbRow[] = [
  {
    id: 'tbl-users',
    schema: 'public',
    name: 'users',
    type: 'Table',
    rows: 1204,
    size: '4.2 MB',
    status: 'Active',
  },
  {
    id: 'tbl-orders',
    schema: 'public',
    name: 'orders',
    type: 'Table',
    rows: 43012,
    size: '128.0 MB',
    status: 'Active',
  },
  {
    id: 'tbl-products',
    schema: 'public',
    name: 'products',
    type: 'Table',
    rows: 890,
    size: '1.1 MB',
    status: 'Idle',
  },
  {
    id: 'vw-revenue',
    schema: 'public',
    name: 'monthly_revenue',
    type: 'View',
    rows: 0,
    size: '0.0 MB',
    status: 'Idle',
  },
  {
    id: 'tbl-sessions',
    schema: 'auth',
    name: 'sessions',
    type: 'Table',
    rows: 52,
    size: '0.4 MB',
    status: 'Active',
  },
  {
    id: 'tbl-audit',
    schema: 'auth',
    name: 'audit_log',
    type: 'Table',
    rows: 12301,
    size: '45.0 MB',
    status: 'Locked',
  },
  {
    id: 'tbl-identities',
    schema: 'auth',
    name: 'identities',
    type: 'Table',
    rows: 104,
    size: '0.8 MB',
    status: 'Active',
  },
  {
    id: 'tbl-objects',
    schema: 'storage',
    name: 'objects',
    type: 'Table',
    rows: 4019,
    size: '12.5 MB',
    status: 'Idle',
  },
  {
    id: 'tbl-buckets',
    schema: 'storage',
    name: 'buckets',
    type: 'Table',
    rows: 4,
    size: '0.1 MB',
    status: 'Idle',
  },
];

const busyRows: DbRow[] = [
  ...demoRows,
  ...Array.from({ length: 24 }, (_, index): DbRow => ({
    id: `busy-${index + 1}`,
    schema: SCHEMAS[index % SCHEMAS.length],
    name: `extra_${String(index + 1).padStart(2, '0')}`,
    type: index % 5 === 0 ? 'View' : 'Table',
    rows: 20 + ((index * 37) % 9000),
    size: `${(0.1 + (index % 9) * 0.4).toFixed(1)} MB`,
    status: STATUSES[index % STATUSES.length],
  })),
];

const rows = pack === 'empty' ? [] : pack === 'busy' ? busyRows : demoRows;
const connections = pack === 'empty' ? 0 : pack === 'busy' ? 12 : 4;

const statusLabel: Record<DbStatus, string> = {
  Active: 'Active',
  Idle: 'Idle',
  Locked: 'Locked',
};
const typeLabel = {
  Table: 'Table',
  View: 'View',
};

function parseMb(size: string): number {
  const value = Number.parseFloat(size);
  if (Number.isNaN(value)) return 0;
  return size.includes('GB') ? value * 1024 : value;
}

function formatMb(mb: number): string {
  if (mb >= 1024) return `${(mb / 1024).toFixed(1)} GB`;
  return `${mb.toFixed(1)} MB`;
}

function groupBySchema(list: DbRow[]) {
  const groups = new Map<string, DbRow[]>();
  for (const row of list) {
    const next = groups.get(row.schema) ?? [];
    next.push(row);
    groups.set(row.schema, next);
  }
  return [...groups.entries()];
}

function StatusBadge({ status, theme }: { status: DbStatus; theme: Theme }) {
  const look = (theme === 'dark' ? STATUS_LOOK_DARK : STATUS_LOOK)[status];
  return (
    <ArcWidgetBadge
      data={{
        value: statusLabel[status],
        fontColor: look.fontColor,
        backgroundColor: look.backgroundColor,
        borderColor: look.backgroundColor,
        borderRadius: '6px',
        fontSize: '10px',
        fontWeight: '600',
        paddingX: '8px',
        paddingY: '3px',
      }}
    />
  );
}

function leafRow(
  row: DbRow,
  selectedIds: Set<string>,
  toggleSelection: (id: string) => void,
  theme: Theme,
  accent: string,
): ArcWidgetTableRow {
  return {
    id: row.id,
    clickable: true,
    rowHeight: '36px',
    rowPaddingY: '4px',
    rowColor: selectedIds.has(row.id)
      ? theme === 'dark'
        ? '#27272A'
        : '#F4F4F5'
      : '',
    columns: [
      {
        width: 'fraction',
        clickable: true,
        value: (
          <div className="flex-row">
            <input
              className="table-check"
              type="checkbox"
              checked={selectedIds.has(row.id)}
              onChange={() => toggleSelection(row.id)}
              onClick={(event) => event.stopPropagation()}
              style={{ '--check-color': accent } as CSSProperties}
            />
            <span className="cell-name cell-name--child">{row.name}</span>
          </div>
        ),
        sort: { value: row.name },
      },
      {
        value: (
          <span className="cell-name cell-name--child">
            {typeLabel[row.type]}
          </span>
        ),
        width: '100px',
      },
      {
        value: <StatusBadge status={row.status} theme={theme} />,
        width: '100px',
      },
      {
        value: (
          <span className="cell-num cell-num--child">
            {row.rows.toLocaleString('en-US')}
          </span>
        ),
        width: '80px',
        alignX: 'right',
        sort: { value: row.rows },
      },
      {
        value: <span className="cell-num cell-num--child">{row.size}</span>,
        width: '110px',
        alignX: 'right',
      },
    ],
  };
}

function buildTableData(
  list: DbRow[],
  selectedIds: Set<string>,
  toggleSelection: (id: string) => void,
  theme: Theme,
): ArcWidgetTableData {
  const dark = theme === 'dark';
  const line = dark ? '#2A3A4E' : '#E4E4E7';
  return {
    height: '360px',
    collapsible: {
      enabled: true,
      expandColumn: 0,
      indentColumn: 0,
      indentSize: '32px',
    } as ArcWidgetTableData['collapsible'] & { indentSize: string },
    rowHoverAction: {
      hoverActive: true,
      backgroundColor: dark ? '#16202A' : '#FAFAFA',
    },
    scrollBar: {
      showScrollBar: true,
      height: '6px',
      backgroundColor: dark ? '#1A2430' : '#F4F4F5',
      handle: {
        backgroundColor: dark ? '#6B8499' : '#A1A1AA',
        borderRadius: '6px',
      },
    },
    header: {
      showHeader: true,
      height: '32px',
      backgroundColor: dark ? '#121820' : '#FAFAFA',
      fontColor: dark ? '#9AADC0' : '#71717A',
      fontSize: '11px',
      columns: [
        { title: 'Name', width: 'fraction' },
        { title: 'Type', width: '100px' },
        { title: 'Status', width: '100px' },
        { title: 'Rows', width: '80px', alignX: 'right' },
        { title: 'Size', width: '110px', alignX: 'right' },
      ],
    },
    styles: {
      backgroundColor: dark ? '#0B1016' : '#FFFFFF',
      fontColor: dark ? '#9AADC0' : '#52525B',
      borderRadius: '8px',
      borders: {
        color: line,
        width: '1px',
        outer: { color: line, width: '1px' },
        columns: false,
        rows: { color: line, width: '1px' },
      },
    },
    table: groupBySchema(list).map(([schema, children]) => {
      const look = SCHEMA_THEME[schema as SchemaName]?.[theme] ?? {
        bg: dark ? '#16202A' : '#F4F4F5',
        ink: dark ? '#E4E4E7' : '#3F3F46',
        track: dark ? '#1A2430' : '#E4E4E7',
      };
      const totalRows = children.reduce((sum, child) => sum + child.rows, 0);
      const totalMb = children.reduce(
        (sum, child) => sum + parseMb(child.size),
        0,
      );
      const active = children.filter(
        (child) => child.status === 'Active',
      ).length;
      return {
        id: `schema-${schema}`,
        clickable: true,
        rowHeight: '36px',
        rowPaddingY: '4px',
        rowColor: look.bg,
        columns: [
          {
            width: 'fraction',
            fontColor: look.ink,
            value: (
              <span
                className="cell-name cell-name--parent"
                style={{ color: look.ink }}
              >
                {schema}
              </span>
            ),
            sort: { value: schema },
          },
          {
            fontColor: look.ink,
            value: (
              <span
                className="cell-name cell-name--parent-meta"
                style={{ color: look.ink }}
              >
                {`${children.length} objects`}
              </span>
            ),
            width: '100px',
          },
          {
            width: '100px',
            value: (
              <ArcWidgetProgressBar
                data={{
                  valueProgress: active,
                  valueTotal: children.length,
                  width: '72px',
                  height: '6px',
                  progressColor: look.ink,
                  backgroundColor: look.track,
                  borderRadius: '4px',
                }}
              />
            ),
          },
          {
            fontColor: look.ink,
            value: (
              <span className="cell-num" style={{ color: look.ink }}>
                {totalRows.toLocaleString('en-US')}
              </span>
            ),
            width: '80px',
            alignX: 'right',
            sort: { value: totalRows },
          },
          {
            width: '110px',
            alignX: 'right',
            fontColor: look.ink,
            value: (
              <span className="size-sum">
                <ArcWidgetIcon
                  data={{
                    name: 'sigma',
                    iconSet: 'phosphor',
                    style: 'regular',
                    iconSize: '12px',
                    color: look.ink,
                  }}
                />
                <span className="cell-num" style={{ color: look.ink }}>
                  {formatMb(totalMb)}
                </span>
              </span>
            ),
          },
        ],
        items: children.map((child) =>
          leafRow(child, selectedIds, toggleSelection, theme, look.ink),
        ),
      };
    }),
    footer: {
      showFooter: true,
      showActionButton: false,
      height: '58px',
      styles: { height: '58px', minHeight: '58px' },
      backgroundColor: dark ? '#121820' : '#FAFAFA',
      leftSideContent: (
        <span className="table-footer__count">
          {selectedIds.size === 0
            ? 'No objects selected'
            : `${selectedIds.size} object${selectedIds.size === 1 ? '' : 's'} selected`}
        </span>
      ),
      rightSideContent: (
        <div className="table-footer__actions">
          <button
            type="button"
            className="btn btn--ghost"
            disabled={selectedIds.size === 0}
          >
            {'Drop Tables'}
          </button>
          <button
            type="button"
            className="btn btn--primary"
            disabled={selectedIds.size === 0}
          >
            {'Export'}
            {selectedIds.size > 0 ? ` (${selectedIds.size})` : ''}
          </button>
        </div>
      ),
    },
    emptyTable: {
      title: 'No data',
      value: 'The query returned 0 rows.',
    },
  };
}

export default function Example() {
  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
  const [theme, setTheme] = useState<Theme>('dark');
  const toggleSelection = (id: string) => {
    setSelectedIds((prev) => {
      const next = new Set(prev);
      if (next.has(id)) next.delete(id);
      else next.add(id);
      return next;
    });
  };
  const tableData = useMemo(
    () => buildTableData(rows, selectedIds, toggleSelection, theme),
    [selectedIds, theme],
  );
  const totalRows = rows.reduce((sum, row) => sum + row.rows, 0);
  const totalMb = rows.reduce((sum, row) => sum + parseMb(row.size), 0);
  const dark = theme === 'dark';
  const kpiValue = dark ? '#F4F4F5' : '#18181B';
  const kpiBorder = dark ? '#2A3A4E' : '#E4E4E7';
  const kpiBg = dark ? '#121820' : '#FAFAFA';
  const kpiCard = (
    card: number,
    title: string,
    value: string,
    color = kpiValue,
  ) => ({
    card,
    title,
    value,
    settings: {
      fontSizeLabel: '10px',
      fontSizeValue: '18px',
      colorValue: color,
      borderColor: kpiBorder,
      backgroundColor: kpiBg,
    },
  });

  return (
    <div className="explorer" data-theme={theme}>
      <style>{`
        .explorer { --ex-fg:#18181b; --ex-muted:#71717a; --ex-bg:#ffffff; --ex-elev:#fafafa; --ex-line:#e4e4e7; --ex-fill:#f4f4f5; --ex-accent:#18181b; --ex-on-accent:#ffffff; --ex-font:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif; --ex-mono:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace; display:grid; gap:12px; background:var(--ex-bg); color:var(--ex-fg); font-family:var(--ex-font); font-size:12px; line-height:1.4; }
        .explorer[data-theme=dark] { --ex-fg:#f4f4f5; --ex-muted:#9aadc0; --ex-bg:#0b1016; --ex-elev:#121820; --ex-line:#2a3a4e; --ex-fill:#1a2430; --ex-accent:#f4f4f5; --ex-on-accent:#0b1016; }
        .explorer * { box-sizing:border-box; }
        .explorer__toolbar { display:flex; justify-content:flex-end; }
        .explorer__kpis { min-height:72px; }
        .explorer__stage { min-width:0; height:360px; }
        .theme-switch { display:inline-flex; align-items:center; padding:3px; border:1px solid var(--ex-line); border-radius:999px; background:var(--ex-elev); gap:2px; }
        .theme-switch button { appearance:none; display:inline-flex; align-items:center; gap:5px; border:0; background:transparent; color:var(--ex-muted); border-radius:999px; padding:4px 10px; font:inherit; font-size:11px; font-weight:500; cursor:pointer; margin:0; }
        .theme-switch button.is-active { background:var(--ex-accent); color:var(--ex-on-accent); }
        .table-footer__count { font-size:11px; color:var(--ex-muted); }
        .table-footer__actions { display:flex; align-items:center; gap:8px; }
        .flex-row { display:flex; align-items:center; gap:8px; }
        .cell-name { font-family:var(--ex-font); font-size:12px; font-weight:400; color:var(--ex-fg); }
        .cell-name--parent { font-weight:700; }
        .cell-name--parent-meta { font-weight:500; }
        .cell-name--child { color:var(--ex-muted); }
        .cell-num { display:block; width:100%; text-align:right; font-family:var(--ex-mono); font-size:11px; font-weight:400; font-variant-numeric:tabular-nums; color:var(--ex-fg); }
        .cell-num--child { color:var(--ex-muted); }
        .size-sum { display:flex; align-items:center; justify-content:flex-end; gap:5px; width:100%; }
        .table-check { appearance:none; width:15px; height:15px; margin:0; flex:0 0 15px; border:1.5px solid var(--check-color,#71717a); border-radius:4px; background:transparent; cursor:pointer; }
        .table-check:checked { background:var(--check-color,#71717a); }
        .table-check:checked::after { content:""; display:block; width:4px; height:7px; margin:1px auto 0; border:solid var(--ex-bg); border-width:0 1.5px 1.5px 0; transform:rotate(45deg); }
        .btn { appearance:none; border:1px solid var(--ex-line); background:transparent; color:inherit; font:inherit; border-radius:6px; padding:5px 12px; font-size:12px; cursor:pointer; font-weight:500; margin:0; }
        .btn--primary { background:var(--ex-accent); color:var(--ex-on-accent); border-color:var(--ex-accent); }
        .btn--ghost { color:var(--ex-fg); }
        .btn:disabled { opacity:.5; cursor:not-allowed; }
      `}</style>
      <div className="explorer__toolbar">
        <div className="theme-switch" role="group" aria-label={'Color theme'}>
          <button
            type="button"
            className={theme === 'light' ? 'is-active' : ''}
            aria-pressed={theme === 'light'}
            onClick={() => setTheme('light')}
          >
            <ArcWidgetIcon
              data={{
                name: 'sun',
                iconSet: 'phosphor',
                style: theme === 'light' ? 'fill' : 'regular',
                iconSize: '14px',
                color: theme === 'light' ? '#18181B' : '#A1A1AA',
              }}
            />
            <span>{'Light'}</span>
          </button>
          <button
            type="button"
            className={theme === 'dark' ? 'is-active' : ''}
            aria-pressed={theme === 'dark'}
            onClick={() => setTheme('dark')}
          >
            <ArcWidgetIcon
              data={{
                name: 'moon',
                iconSet: 'phosphor',
                style: theme === 'dark' ? 'fill' : 'regular',
                iconSize: '14px',
                color: theme === 'dark' ? '#F4F4F5' : '#71717A',
              }}
            />
            <span>{'Dark'}</span>
          </button>
        </div>
      </div>
      <div className="explorer__kpis">
        <ArcWidgetKpiBar
          data={{
            settings: {
              height: '72px',
              fontSizeLabel: '10px',
              fontSizeValue: '18px',
              colorLabel: dark ? '#9AADC0' : '#71717A',
              borderColor: kpiBorder,
              backgroundColor: kpiBg,
            },
            cards: [
              kpiCard(1, 'Total Rows', totalRows.toLocaleString('en-US')),
              kpiCard(2, 'Total Size', formatMb(totalMb)),
              kpiCard(
                3,
                'Connections',
                String(connections),
                dark ? '#86EFAC' : '#15803D',
              ),
            ],
          }}
        />
      </div>
      <div className="explorer__stage">
        <ArcWidgetTable
          key={`intro-explorer-${theme}`}
          data={tableData}
        />
      </div>
    </div>
  );
}
```

Kennzahlen und Tabelle kommen aus denselben React-Daten. Theme und Auswahl bleiben lokaler 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).
<!-- /host -->

<!-- host:ninox -->
# 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).

![](https://framerusercontent.com/images/wU0ZV7W9mfUZgbvDBO8vdyPuH4c.png)
<!-- /host -->

<!-- host:vue -->
# 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).
<!-- /host -->


---

# Widgets und Mini-Widgets

Source: https://www.arc-rider.com/docs/intro/widgets-und-mini-widgets


<!-- host:react -->
# 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

<!-- react-example: layout-01-form_numbers.tsx -->
```tsx
import {
  ArcWidgetBadge,
  ArcWidgetInput,
  ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';

const row = (number: string, title: string) => ({
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        gap: '12px',
        height: '48px',
        blocks: [
          {
            width: '52px',
            value: (
              <ArcWidgetBadge
                data={{
                  value: number,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
          {
            width: 'fraction',
            value: (
              <ArcWidgetInput
                data={{
                  type: 'number',
                  labelSettings: { title },
                  numpad: { suffix: '€' },
                }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        gap: '8px',
        width: '420px',
        blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')],
      }}
    />
  );
}
```

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).
<!-- /host -->

<!-- host:ninox -->
# 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.


![](https://framerusercontent.com/images/OUceOtboxPQac3AJ3N3DEu9yas.png)

## 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`, …


![](https://framerusercontent.com/images/qSmv08CT1x4gwgcOSt9jEYdtJs.png)

## 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).
<!-- /host -->

<!-- host:vue -->
# 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`.


![](https://framerusercontent.com/images/OUceOtboxPQac3AJ3N3DEu9yas.png)

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


![](https://framerusercontent.com/images/qSmv08CT1x4gwgcOSt9jEYdtJs.png)

## 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).
<!-- /host -->


---

# React einrichten

Source: https://www.arc-rider.com/docs/intro/setup-react


# React einrichten

arcWidgets liefert 24 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.6
```

Diese Dokumentation gehört zu `0.1.0-alpha.6`. 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 startLanes = [
  {
    id: 'open',
    title: 'Open',
    items: [
      {
        id: 'brief',
        title: 'Prepare quote',
        tag: 'Today',
        color: '#d97706',
      },
    ],
  },
  {
    id: 'done',
    title: 'Done',
    items: [] as { id: string; title: string; tag: string; color: string }[],
  },
];

export default function Example() {
  const [lanes, setLanes] = useState(startLanes);
  const [selected, setSelected] = useState('Drag or click a card');
  return (
    <>
      <ArcWidgetKanban
        data={{
          height: '300px',
          swimlanes: lanes.map((lane) => ({
            ...lane,
            items: lane.items.map((item) => ({
              id: item.id,
              title: item.title,
              subtitle: (
                <ArcWidgetBadge
                  data={{
                    value: item.tag,
                    singleColor: item.color,
                    borderRadius: '6px',
                  }}
                />
              ),
              clickable: true,
              draggable: true,
              borderPosition: 'left',
              borderColor: item.color,
              borderWidth: '4px',
            })),
          })),
        }}
        onItemClick={(_event, { item_index }) =>
          setSelected(`Task ${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('Card moved');
        }}
      />
      <p aria-live="polite">{selected}</p>
    </>
  );
}
```

## 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/widgets/`. 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 24 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
<script setup>
import { ArcWidgetTable } from '@arcrider/arcwidgets-vue';
import '@arcrider/arcwidgets-vue/styles.css';

const tableData = {
  uniqueListId: 'orders',
  rows: [
    { id: 'order-42', columns: [{ value: 'Order 42' }] },
    { id: 'order-43', columns: [{ value: 'Order 43' }] },
  ],
};

function onAction(action) {
  // handle updates, persist data, navigate
}
</script>

<template>
  <ArcWidgetTable id="orders" :data="tableData" @action="onAction" />
</template>
```

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)
- `ArcWidgetGrid` — [Grid](/docs/react/widgets/custom-grid)
- `ArcWidgetIcon` — [Icon](/docs/react/mini-widgets/custom-icon)
- `ArcWidgetImage` — [Image](/docs/react/mini-widgets/images)
- `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/widgets/`.

## 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/).

<!-- host:ninox -->
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).
<!-- /host -->

<!-- host:react -->
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).
<!-- /host -->

<!-- host:vue -->
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).
<!-- /host -->


---

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

![ADK Setup Guide: Projektordner und fertiger Widget-Code in Cursor](/docs-assets/adk/01-folder.png)

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

![Node.js, Ninox und Arc Rider](/docs-assets/adk/02-nodejs.png)

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

![Cursor herunterladen](/docs-assets/adk/03-cursor.png)

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

![Projektordner in Cursor öffnen](/docs-assets/adk/04-open-folder.png)

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

![ADK-Installation im Terminal und die neuen Ordner in der Sidebar](/docs-assets/adk/05-install.png)

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

![API-Key in den Ninox-Einstellungen anlegen](/docs-assets/adk/06-api-key.png)

### 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`.

![Zugangsdaten in ninox/config.yaml](/docs-assets/adk/07-config.png)

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

![Heruntergeladenes Ninox-Schema in Cursor](/docs-assets/adk/08-schema.png)

## 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/`.

![Erster Prompt und generierter Widget-Code](/docs-assets/adk/09-prompt.png)

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

![Fertiges Widget in Ninox](/docs-assets/adk/10-ninox.png)

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


<!-- host:react -->
# 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

<!-- react-example: calendar_week-00-defaults.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetCalendarWeek } from '@arcrider/arcwidgets-react';
import type {
  ArcWidgetCalendarWeekCreatePayload,
  ArcWidgetCalendarWeekDailyEntryDragSavePayload,
  ArcWidgetCalendarWeekDragSourcePayload,
  ArcWidgetCalendarWeekEntryDragSavePayload,
  ArcWidgetCalendarWeekTimeEntry,
} from '@arcrider/arcwidgets-react';

const DAY = 86400000;
const monday = new Date(2027, 0, 4).getTime();
const day = (index: number) => monday + index * DAY;
const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;

const initialEntries: ArcWidgetCalendarWeekTimeEntry[] = [
  {
    title: 'Team Offsite',
    subtitle: '2 days',
    dateFrom: day(0),
    dateTo: day(1),
    draggable: true,
  },
  {
    title: 'Public Holiday',
    subtitle: 'All-day',
    dateFrom: day(2),
    dateTo: day(2),
    draggable: true,
  },
  {
    title: 'Team Meeting',
    subtitle: '09:00 - 10:30',
    dateFrom: day(0),
    dateTo: day(0),
    timeFrom: at(9),
    timeTo: at(10, 30),
    draggable: true,
  },
  {
    title: 'Code Review',
    subtitle: '10:00 - 11:00',
    dateFrom: day(1),
    dateTo: day(1),
    timeFrom: at(10),
    timeTo: at(11),
    draggable: true,
  },
  {
    title: 'Workshop',
    subtitle: '13:30 - 17:00',
    dateFrom: day(1),
    dateTo: day(1),
    timeFrom: at(13, 30),
    timeTo: at(17),
    insetBorder: { stroke: 'dotted' },
    draggable: true,
  },
  {
    title: 'Sprint Planning',
    subtitle: '09:00 - 12:00',
    dateFrom: day(4),
    dateTo: day(4),
    timeFrom: at(9),
    timeTo: at(12),
    draggable: true,
  },
];

export default function Example() {
  // Only the visible week, hours and entries are set; look and behavior are widget defaults.
  // Entries without times span whole days: one day (Public Holiday) or several (Team Offsite).
  // Inset line: every timed entry shows a vertical line on its left edge (all-day entries do not).
  // It takes the entry's `styles.color`, or #18181b. `insetBorder` on an entry changes that entry:
  // `stroke` ('solid', 'dashed' or 'dotted'), `width`, `color`, `position` ('left' or 'right'),
  // `enabled: false` hides it. Put `insetBorder` on `data` to apply it to all entries
  // (see the Minimalistic example); fields set on an entry win over it.
  //
  // Drag and save: `draggable: true` lets an entry be moved. The calendar only reports the drop.
  // Write `endData` into the entry at `source.entry_index`, then save it to your API.
  // If saving fails, put `startData` back. Without this step the entry jumps back on the next update.
  //
  // Create: `createNew` turns on drawing a new range over empty slots (or over the all-day row).
  // `onCreate` reports it; your app validates it, gives it an id and saves it. Without `createNew`
  // dragging over empty slots does nothing.
  const [entries, setEntries] = useState(initialEntries);

  const persist = (
    source: ArcWidgetCalendarWeekDragSourcePayload,
    endData: ArcWidgetCalendarWeekEntryDragSavePayload | ArcWidgetCalendarWeekDailyEntryDragSavePayload,
  ) => {
    setEntries((current) =>
      current.map((entry, index) => (index === source.entry_index ? { ...entry, ...endData } : entry)),
    );
  };

  const create = (values: ArcWidgetCalendarWeekCreatePayload) => {
    const allDay = values.timeFrom === undefined;
    setEntries((current) => [
      ...current,
      {
        id: `new-${current.length + 1}`,
        title: 'New entry',
        subtitle: allDay ? 'All-day' : undefined,
        ...values,
        draggable: true,
      },
    ]);
  };

  return (
    <ArcWidgetCalendarWeek
      data={{
        lang: 'en',
        dateSettings: { startDate: monday, duration: 7 },
        timeSettings: { timeStart: at(8), duration: at(12) },
        height: '800px',
        createNew: {},
        timeEntries: entries,
      }}
      onCreate={create}
      onEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, endData)}
      onDailyEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, endData)}
    />
  );
}
```

## Features ausprobieren

### Tagesansichten, Terminbearbeitung und JSX

Ein gemeinsamer State steuert die Zahl der Tage und den Terminbeginn. Drag persistiert über `onEntryDragSave` mit **`endData`**.

<!-- react-example: calendar_week-00-defaults.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetCalendarWeek } from '@arcrider/arcwidgets-react';
import type {
  ArcWidgetCalendarWeekCreatePayload,
  ArcWidgetCalendarWeekDailyEntryDragSavePayload,
  ArcWidgetCalendarWeekDragSourcePayload,
  ArcWidgetCalendarWeekEntryDragSavePayload,
  ArcWidgetCalendarWeekTimeEntry,
} from '@arcrider/arcwidgets-react';

const DAY = 86400000;
const monday = new Date(2027, 0, 4).getTime();
const day = (index: number) => monday + index * DAY;
const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;

const initialEntries: ArcWidgetCalendarWeekTimeEntry[] = [
  {
    title: 'Team Offsite',
    subtitle: '2 days',
    dateFrom: day(0),
    dateTo: day(1),
    draggable: true,
  },
  {
    title: 'Public Holiday',
    subtitle: 'All-day',
    dateFrom: day(2),
    dateTo: day(2),
    draggable: true,
  },
  {
    title: 'Team Meeting',
    subtitle: '09:00 - 10:30',
    dateFrom: day(0),
    dateTo: day(0),
    timeFrom: at(9),
    timeTo: at(10, 30),
    draggable: true,
  },
  {
    title: 'Code Review',
    subtitle: '10:00 - 11:00',
    dateFrom: day(1),
    dateTo: day(1),
    timeFrom: at(10),
    timeTo: at(11),
    draggable: true,
  },
  {
    title: 'Workshop',
    subtitle: '13:30 - 17:00',
    dateFrom: day(1),
    dateTo: day(1),
    timeFrom: at(13, 30),
    timeTo: at(17),
    insetBorder: { stroke: 'dotted' },
    draggable: true,
  },
  {
    title: 'Sprint Planning',
    subtitle: '09:00 - 12:00',
    dateFrom: day(4),
    dateTo: day(4),
    timeFrom: at(9),
    timeTo: at(12),
    draggable: true,
  },
];

export default function Example() {
  // Only the visible week, hours and entries are set; look and behavior are widget defaults.
  // Entries without times span whole days: one day (Public Holiday) or several (Team Offsite).
  // Inset line: every timed entry shows a vertical line on its left edge (all-day entries do not).
  // It takes the entry's `styles.color`, or #18181b. `insetBorder` on an entry changes that entry:
  // `stroke` ('solid', 'dashed' or 'dotted'), `width`, `color`, `position` ('left' or 'right'),
  // `enabled: false` hides it. Put `insetBorder` on `data` to apply it to all entries
  // (see the Minimalistic example); fields set on an entry win over it.
  //
  // Drag and save: `draggable: true` lets an entry be moved. The calendar only reports the drop.
  // Write `endData` into the entry at `source.entry_index`, then save it to your API.
  // If saving fails, put `startData` back. Without this step the entry jumps back on the next update.
  //
  // Create: `createNew` turns on drawing a new range over empty slots (or over the all-day row).
  // `onCreate` reports it; your app validates it, gives it an id and saves it. Without `createNew`
  // dragging over empty slots does nothing.
  const [entries, setEntries] = useState(initialEntries);

  const persist = (
    source: ArcWidgetCalendarWeekDragSourcePayload,
    endData: ArcWidgetCalendarWeekEntryDragSavePayload | ArcWidgetCalendarWeekDailyEntryDragSavePayload,
  ) => {
    setEntries((current) =>
      current.map((entry, index) => (index === source.entry_index ? { ...entry, ...endData } : entry)),
    );
  };

  const create = (values: ArcWidgetCalendarWeekCreatePayload) => {
    const allDay = values.timeFrom === undefined;
    setEntries((current) => [
      ...current,
      {
        id: `new-${current.length + 1}`,
        title: 'New entry',
        subtitle: allDay ? 'All-day' : undefined,
        ...values,
        draggable: true,
      },
    ]);
  };

  return (
    <ArcWidgetCalendarWeek
      data={{
        lang: 'en',
        dateSettings: { startDate: monday, duration: 7 },
        timeSettings: { timeStart: at(8), duration: at(12) },
        height: '800px',
        createNew: {},
        timeEntries: entries,
      }}
      onCreate={create}
      onEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, endData)}
      onDailyEntryDragSave={(_entryIndex, _startData, endData, source) => persist(source, endData)}
    />
  );
}
```

### Segmente der Inset-Linie

Teile die Inset-Linie eines Eintrags in `segments`, zum Beispiel eine Farbe pro Person. Ein Segment mit Zeit (`timeFrom` + `timeTo` oder `offset` + `duration`) sitzt dort, wo die Zeit liegt; überlappende Segmente werden nebeneinander gezeichnet. Ohne Zeiten teilen sich die Segmente die Linie nach `size`. `label` erscheint als Tooltip.

<!-- react-example: calendar_week-08-inset_segments.tsx -->
```tsx
import { ArcWidgetCalendarWeek } from '@arcrider/arcwidgets-react';
import type { ArcWidgetCalendarWeekTimeEntry } from '@arcrider/arcwidgets-react';

const DAY = 86400000;
const monday = new Date(2027, 0, 4).getTime();
const day = (index: number) => monday + index * DAY;
const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;
const minutes = (count: number) => count * 60000;

const people = {
  anna: { label: 'Anna', color: '#DC2626' },
  ben: { label: 'Ben', color: '#2563EB' },
  clara: { label: 'Clara', color: '#16A34A' },
};

// The inset line of an entry can be cut into `segments`, for example one per person.
// Each segment has its own `color` and a `label` that appears as a tooltip.
const entries: ArcWidgetCalendarWeekTimeEntry[] = [
  {
    // Segments with clock times sit where their time is. Where two overlap (10:00 - 10:30)
    // they are drawn side by side. Time with no segment (11:30 - 12:00) stays empty: nobody is assigned.
    title: 'Team Meeting',
    subtitle: 'Anna and Ben',
    dateFrom: day(0),
    dateTo: day(0),
    timeFrom: at(9),
    timeTo: at(12),
    insetBorder: {
      segments: [
        { ...people.anna, timeFrom: at(9), timeTo: at(10, 30) },
        { ...people.ben, timeFrom: at(10), timeTo: at(11, 30) },
      ],
    },
  },
  {
    // `offset` counts from the start of the entry, so these segments move with it.
    title: 'Customer Workshop',
    subtitle: 'Handover between two people',
    dateFrom: day(1),
    dateTo: day(1),
    timeFrom: at(13),
    timeTo: at(16),
    insetBorder: {
      segments: [
        { ...people.clara, offset: 0, duration: minutes(90) },
        { ...people.ben, offset: minutes(90), duration: minutes(90) },
      ],
    },
  },
  {
    // Without times the segments share the line: 'fraction' (or 'auto') splits what is left equally,
    // '25%' or '24px' are fixed. `stroke` styles all segments that do not set their own.
    title: 'Planning',
    subtitle: 'Three people, one share each',
    dateFrom: day(2),
    dateTo: day(2),
    timeFrom: at(9),
    timeTo: at(11),
    insetBorder: {
      stroke: 'dotted',
      segments: [
        { ...people.anna },
        { ...people.ben },
        { ...people.clara, stroke: 'solid', size: '25%' },
      ],
    },
  },
  {
    title: 'Site Visit',
    subtitle: 'Default line',
    dateFrom: day(3),
    dateTo: day(3),
    timeFrom: at(10),
    timeTo: at(12),
  },
];

export default function Example() {
  return (
    <ArcWidgetCalendarWeek
      data={{
        lang: 'en',
        dateSettings: { startDate: monday, duration: 5 },
        timeSettings: { timeStart: at(8), duration: at(10) },
        height: '620px',
        timeEntries: entries,
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

0-basierter Index des geklickten Stücks. Feuert nur bei Einträgen mit `clickable: true`. Segmente und Splits werden zu einzelnen Stücken aufgefaltet; der Index entspricht `data.timeEntries` nur bei Einträgen ohne `segments`.

```typescript
onEntryClick?: (entryIndex: number) => void;
```

### onDayClick

Gewählter Tag als Epoch-Millisekunden um 00:00 UTC. Feuert beim Klick auf den Tageskopf mit `dateSettings.day.clickable: true`.

```typescript
onDayClick?: (dateMillis: number) => void;
```

### onEntryDragSave

Drag-Ende eines Stücks mit Uhrzeit: `startData` (vorher) und `endData` (Drop-Ziel) — persistiere `endData`. `source` verortet das Stück in deinen `timeEntries` (`entry_index`, `segment_index`, `split_index`). Bewegt sich eine Segmentgruppe gemeinsam, feuert der Callback einmal pro bewegtem Stück.

```typescript
onEntryDragSave?: (
	entryIndex: number,
	startData: ArcWidgetCalendarWeekEntryDragSavePayload,
	endData: ArcWidgetCalendarWeekEntryDragSavePayload,
	source: ArcWidgetCalendarWeekDragSourcePayload
) => void;
```

### onDailyEntryDragSave

Drag-Ende eines ganztägigen Termins: `startData` und `endData` nur mit `dateFrom` / `dateTo` — persistiere `endData`.

```typescript
onDailyEntryDragSave?: (
	entryIndex: number,
	startData: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
	endData: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
	source: ArcWidgetCalendarWeekDragSourcePayload
) => void;
```

### onCreate

Neuer Bereich, über leere Slots gezogen, oder ein platziertes `createNew.item`. Benötigt `createNew`. Bei einem ganztägigen Bereich fehlen `timeFrom` / `timeTo`. Validieren und Speichern übernimmt die Anwendung.

```typescript
onCreate?: (values: ArcWidgetCalendarWeekCreatePayload) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### width

Breite des Widgets, z. B. `"100%"`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### styles

Rahmen, Rasterlinien, Kopfzeilenfläche und Texttöne (`borders`, `borderColor`, `borderSize`, `borderRadius`, `backgroundColor`, `headerBackgroundColor`, `fontColor`, `mutedColor`, `subtleColor`).

Typ: `ArcWidgetCalendarWeekStyles`.

### weekdaySettings

ISO-Kalenderwoche und Jahr, wenn `dateSettings.startDate` fehlt, z. B. `{ week: 1, year: 2027 }`. Der Bereich beginnt dann um 00:00 UTC am ersten Tag dieser Woche.

Typ: `ArcWidgetCalendarWeekdaySettings`.

### weekStart

Erster Wochentag für `weekdaySettings` und die Standardwoche: `1` = Montag … `7` = Sonntag. Standard: `1`.

Typ: `number`.

### dateSettings

Sichtbarer Bereich, Tageskopf und Markierungen. `startDate` (Epoch-Millisekunden) legt den ersten sichtbaren Tag fest und hat Vorrang vor `weekdaySettings`; Termindaten werden relativ dazu platziert. `endDate` (exklusiv) oder `duration` (Tage, Standard `7`) legt die Länge fest. Samstag und Sonntag sind standardmäßig leicht grau getönt; eine Markierung für diese Tage ersetzt die Farbe, `backgroundColor: 'transparent'` entfernt sie. `weekends: false` blendet Samstag und Sonntag von Anfang an aus (im Einstellungsmenü lassen sie sich wieder einblenden).

Typ: `ArcWidgetCalendarWeekDateSettings`.

### timeZoneBalance

Stundenversatz, der auf die Stundenlabels und Uhrzeit-Labels der Termine addiert wird, z. B. `-1`; die Position der Termine bleibt gleich. Standard: `0`.

Typ: `number`.

### timeSettings

Sichtbare Stunden des Tages: `timeStart` und `duration` in Millisekunden (`8 * 3600000` = 08:00). Standard: der ganze Tag.

Typ: `ArcWidgetCalendarWeekTimeSettings`.

### currentTime

`true` zeigt eine Linie für die aktuelle Uhrzeit; ein Farbstring wie `"#f95757"` setzt zusätzlich ihre Farbe. Standard: `false`.

Typ: `boolean | string`.

### dragStep

Rasterschritt beim Ziehen und Erstellen in Millisekunden. Standard: `300000` (5 Minuten).

Typ: `number`.

### lang

Locale für Wochentags- und Monatsnamen sowie die Toolbar. Standard: `"de"`.

Typ: `string`.

### timeSlotWidth

Mindestbreite einer Tagesspalte, z. B. `"200px"`.

Typ: `string`.

### timeSlotHeight

Mindesthöhe einer Stundenzeile. Standard: `"50px"`. Ist der Kalender höher, als alle Stunden bei dieser Höhe brauchen, werden die Zeilen gleichmäßig gestreckt; unter der letzten Stunde bleibt keine leere Fläche. Ist er niedriger, scrollt er.

Typ: `string`.

### allDayHeight

Höhe des Bereichs für ganztägige Termine, z. B. `"120px"`. Standard: passt sich den Einträgen an.

Typ: `string`.

### createNew

Aktiviert das Erstellen von Terminen; der neue Bereich kommt in `onCreate` an. Ohne `item` zieht man einen Bereich über leere Slots. Mit `item` folgt ein vorgefertigter Termin dem Zeiger und wird per Klick platziert.

Typ: `ArcWidgetCalendarWeekCreateNew`.

### segmentSettings

Drag-Verhalten segmentierter Einträge: `dayJump`, `lockGroups`, `edgeMagnetism` und die Segment-`toolbar`.

Typ: `ArcWidgetCalendarWeekSegmentSettings`.

### insetBorder

Vertikale Linie am linken Rand jedes Eintrags mit Uhrzeit; ganztägige Einträge zeigen sie nicht. Standardmäßig aktiv. Mit `{ enabled: false }` blendest du sie überall aus, mit `stroke`, `width`, `color` und `position` gestaltest du alle Linien um. Ein `insetBorder` an einem einzelnen Eintrag oder Segment hat feldweise Vorrang. Mit `segments` teilst du die Linie in Stücke, z. B. eines pro Person, auf Wunsch nach Zeit platziert (siehe unten).

Typ: `ArcWidgetCalendarWeekInsetBorder`.

### timeEntries

Termine mit Datumswerten, Uhrzeiten und Inhalten. Beide Zeiten weglassen für einen Ganztagsbalken.

Typ: `ArcWidgetCalendarWeekTimeEntry[]`.

## Verhalten und Grenzen

- Für JSX in Terminen verwende `customLayout`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet.

- Datumswerte sind Epoch-Millisekunden in derselben Zeitbasis wie `dateSettings.startDate`, z. B. `new Date(2027, 0, 4).getTime()` für beide; Uhrzeiten sind Millisekunden seit Tagesbeginn (`9 * 3600000` = 09:00). 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.

- Drag: `draggable: true` auf dem Eintrag. Callback `onEntryDragSave(entryIndex, startData, endData, source)` / `onDailyEntryDragSave` — persistiere **`endData`** an `source.entry_index` / `source.segment_index`. `startData` ist der Stand vor dem Zug. Ohne `draggable: true` lässt sich der Eintrag nicht verschieben.

- Ablegen speichern, Schritt für Schritt: (1) `endData` in den Eintrag an `source.entry_index` in deinem `timeEntries`-State schreiben, (2) im Backend speichern, (3) bei einem Fehler `startData` zurücksetzen. Der Kalender zeichnet aus den `timeEntries`, die du übergibst; ein nicht aktualisierter Eintrag springt beim nächsten Update an seine alte Position zurück. Vollständiges Beispiel: `calendar_week-00-defaults.tsx`.

- Der sichtbare Uhrzeitbereich wird über `timeSettings.timeStart` und `timeSettings.duration` in Millisekunden konfiguriert.

- `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` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: calendar_week -->
```typescript
export type ArcWidgetCalendarWeekBorderLine =
	| boolean
	| {
			enabled?: boolean;
			color?: string;
			width?: string;
	  };

export interface ArcWidgetCalendarWeekBorders {
	color?: string;
	width?: string;
	outer?: ArcWidgetCalendarWeekBorderLine;
	columns?: ArcWidgetCalendarWeekBorderLine;
	rows?: ArcWidgetCalendarWeekBorderLine;
}

export interface ArcWidgetCalendarWeekStyles {
	borders?: ArcWidgetCalendarWeekBorders;
	borderColor?: string;
	borderSize?: string;
	borderRadius?: string;
	backgroundColor?: string;
	headerBackgroundColor?: string;
	fontColor?: string;
	mutedColor?: string;
	subtleColor?: string;
}

export interface ArcWidgetCalendarWeekHeaderText {
	label?: string;
	fontSize?: string;
	fontColor?: string;
	fontWeight?: string | number;
	alignX?: 'left' | 'center' | 'right';
}

export interface ArcWidgetCalendarWeekHeader {
	backgroundColor?: string;
	title?: ArcWidgetCalendarWeekHeaderText;
	subtitle?: ArcWidgetCalendarWeekHeaderText;
}

export interface ArcWidgetCalendarWeekHighlightStyles {
	backgroundColor?: string;
	borderColor?: string;
	borderSize?: string;
	borders?: Pick<ArcWidgetCalendarWeekBorders, 'color' | 'width' | 'columns' | 'rows'>;
}

export interface ArcWidgetCalendarWeekHighlight {
	date?: number | string;
	weekday?: number;
	color?: string;
	styles?: ArcWidgetCalendarWeekHighlightStyles;
	title?: ArcWidgetCalendarWeekHeaderText;
	subtitle?: ArcWidgetCalendarWeekHeaderText;
}

export interface ArcWidgetCalendarWeekDay {
	clickable?: boolean;
}

export interface ArcWidgetCalendarWeekDateSettings {
	startDate?: number;
	endDate?: number;
	duration?: number;
	weekends?: boolean;
	header?: ArcWidgetCalendarWeekHeader;
	day?: ArcWidgetCalendarWeekDay;
	highlights?: ArcWidgetCalendarWeekHighlight[];
}

export interface ArcWidgetCalendarWeekdaySettings {
	week?: number;
	year?: number;
}

export interface ArcWidgetCalendarWeekTimeSettings {
	timeStart?: number;
	duration?: number;
}

export interface ArcWidgetCalendarWeekDayJump {
	threshold?: number;
	startTime?: number;
}

export interface ArcWidgetCalendarWeekSegmentSettings {
	dayJump?: ArcWidgetCalendarWeekDayJump;
	lockGroups?: boolean;
	edgeMagnetism?: boolean;
	toolbar?: boolean;
}

export interface ArcWidgetCalendarWeekInsetSegment {
	color?: string;
	stroke?: 'solid' | 'dashed' | 'dotted';
	label?: string;
	size?: 'fraction' | 'auto' | (string & {});
	timeFrom?: number;
	timeTo?: number;
	offset?: number;
	duration?: number;
}

export interface ArcWidgetCalendarWeekInsetBorder {
	enabled?: boolean;
	position?: 'left' | 'right';
	width?: string;
	stroke?: 'solid' | 'dashed' | 'dotted';
	color?: string;
	align?: 'start' | 'center' | 'end';
	segments?: ArcWidgetCalendarWeekInsetSegment[];
}

export type ArcWidgetCalendarWeekEntryStyles = ArcWidgetCssProperties;

export interface ArcWidgetCalendarWeekSplit {
	title?: string;
	subtitle?: string;
	value?: string;
	customLayout?: ArcWidgetSlot;
	styles?: ArcWidgetCalendarWeekEntryStyles;
	insetBorder?: ArcWidgetCalendarWeekInsetBorder;
	timeFrom?: number;
	timeTo?: number;
	offset?: number;
	duration?: number;
}

export interface ArcWidgetCalendarWeekSegment {
	title?: string;
	subtitle?: string;
	value?: string;
	customLayout?: ArcWidgetSlot;
	styles?: ArcWidgetCalendarWeekEntryStyles;
	insetBorder?: ArcWidgetCalendarWeekInsetBorder;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	linked?: boolean;
	segmentSettings?: Pick<ArcWidgetCalendarWeekSegmentSettings, 'dayJump'>;
	splits?: ArcWidgetCalendarWeekSplit[];
	clickable?: boolean;
	draggable?: boolean;
}

export interface ArcWidgetCalendarWeekTimeEntry {
	id?: string | number;
	title?: string;
	subtitle?: string;
	value?: string;
	customLayout?: ArcWidgetSlot;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	styles?: ArcWidgetCalendarWeekEntryStyles;
	insetBorder?: ArcWidgetCalendarWeekInsetBorder;
	clickable?: boolean;
	draggable?: boolean;
	segments?: ArcWidgetCalendarWeekSegment[];
	segmentSettings?: Pick<ArcWidgetCalendarWeekSegmentSettings, 'dayJump'>;
}

export interface ArcWidgetCalendarWeekPlaceOffset {
	days?: number;
	time?: number;
}

export interface ArcWidgetCalendarWeekPlaceSegment {
	title?: string;
	subtitle?: string;
	value?: string;
	customLayout?: ArcWidgetSlot;
	styles?: ArcWidgetCalendarWeekEntryStyles;
	insetBorder?: ArcWidgetCalendarWeekInsetBorder;
	linked?: boolean;
	duration?: number;
	offset?: ArcWidgetCalendarWeekPlaceOffset;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	splits?: ArcWidgetCalendarWeekSplit[];
}

export interface ArcWidgetCalendarWeekPlaceItem extends ArcWidgetCalendarWeekPlaceSegment {
	active?: boolean;
	segments?: ArcWidgetCalendarWeekPlaceSegment[];
}

export interface ArcWidgetCalendarWeekCreateNew {
	item?: ArcWidgetCalendarWeekPlaceItem | null;
}

export interface ArcWidgetCalendarWeekData {
	width?: string;
	height?: string;
	lang?: string;
	weekStart?: number;
	weekdaySettings?: ArcWidgetCalendarWeekdaySettings;
	dateSettings?: ArcWidgetCalendarWeekDateSettings;
	timeSettings?: ArcWidgetCalendarWeekTimeSettings;
	timeZoneBalance?: number;
	currentTime?: boolean | string;
	dragStep?: number;
	timeSlotWidth?: string;
	timeSlotHeight?: string;
	allDayHeight?: string;
	styles?: ArcWidgetCalendarWeekStyles;
	createNew?: ArcWidgetCalendarWeekCreateNew;
	segmentSettings?: ArcWidgetCalendarWeekSegmentSettings;
	insetBorder?: ArcWidgetCalendarWeekInsetBorder;
	timeEntries?: ArcWidgetCalendarWeekTimeEntry[];
}

export interface ArcWidgetCalendarWeekEntryDragSavePayload {
	dateFrom: number;
	dateTo: number;
	timeFrom: number;
	timeTo: number;
}

export interface ArcWidgetCalendarWeekDailyEntryDragSavePayload {
	dateFrom: number;
	dateTo: number;
}

export interface ArcWidgetCalendarWeekDragSourcePayload {
	entry_index: number;
	segment_index: number | null;
	split_index: number | null;
}

export interface ArcWidgetCalendarWeekCreatePayload {
	dateFrom: number;
	dateTo: number;
	timeFrom?: number;
	timeTo?: number;
}

export interface ArcWidgetCalendarWeekProps extends ArcReactWidgetProps<ArcWidgetCalendarWeekData> {
	onEntryClick?: (entryIndex: number) => void;
	onDayClick?: (dateMillis: number) => void;
	onEntryDragSave?: (
		entryIndex: number,
		startData: ArcWidgetCalendarWeekEntryDragSavePayload,
		endData: ArcWidgetCalendarWeekEntryDragSavePayload,
		source: ArcWidgetCalendarWeekDragSourcePayload
	) => void;
	onDailyEntryDragSave?: (
		entryIndex: number,
		startData: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
		endData: ArcWidgetCalendarWeekDailyEntryDragSavePayload,
		source: ArcWidgetCalendarWeekDragSourcePayload
	) => void;
	onCreate?: (values: ArcWidgetCalendarWeekCreatePayload) => 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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)

<iframe src="https://www.youtube.com/embed/ln3SRc_Cv9k?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>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**.

<pre data-language="JavaScript">`timeSlotWidth:  "250px" ,`</pre>→ 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 mindestens dargestellt wird**.

<pre data-language="JavaScript">`timeSlotHeight: "80px",`</pre>→ Jede Stunde erhält mindestens eine **Höhe von 80 Pixeln** in der vertikalen Zeitachse.

📌 **Hinweis:**

- Der Standardwert liegt bei **50 px**.
- Ein höherer Wert sorgt für **mehr Raum pro Stunde.**
- Ist der Kalender höher als die Stunden bei dieser Mindesthöhe brauchen, werden die Zeilen **automatisch gestreckt** und füllen die Höhe aus.

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

<pre data-language="JavaScript"><code>	styles: {
            backgroundColor: "rgba(0,0,255,0.01)"
        },</code></pre>### 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.

<pre data-language="JavaScript"><code>title: Kalendertitel, // Ninox Feld
title: "", // Default: Gibt die Uhrzeit des Kalendereintrages an</code></pre>📌 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.

<pre data-language="JavaScript"><code>subtitle: Description, // Ninox Feld
subtitle: "" // Textfeld</code></pre>→ 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.:</p><ul><li data-preset-tag="p"><p>Ein Select-Feld, um den zuständigen Mitarbeiter auszuwählen
- Ein Input-Feld für kurze Notizen oder Rückmeldungen

</li></ul><pre data-language="JavaScript"><code>value: "",
value: Kommentar, </code></pre>→ 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.

<pre data-language="JavaScript">`customLayout: "",`</pre>💡 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',
```

![](https://framerusercontent.com/images/zRF7pUd7VZBvsfI8yuyCarMGYs.png)

📌 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).

<pre data-language="JavaScript"><code>styles: {
                    backgroundColor: color(Person),
                    color: "#fff",
                    borderRadius: "8px",
                    padding: ""
                },</code></pre>📌 **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.

<pre data-language="JavaScript"><code>clickAction: {
                    type: "popup",
                    recordId: Nr
                }</code></pre>📌 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 **mit Uhrzeit** anzeigen lassen – ähnlich dem Stil des Apple Kalenders. Ganztägige Einträge zeigen sie nicht. Das Feature ist **standardmäßig aktiv** und muss nur deaktiviert werden, wenn du es nicht möchtest.

```javascript
// On data: applies to all timed entries (hide everywhere with enabled: false)
insetBorder: { enabled: false }

// On a timeEntry or segment: applies to that entry only
insetBorder: {
    enabled: true,       // default: true; false hides the line
    position: 'left',    // 'left' (default) or 'right'
    width: '2px',        // line width, default: 3px
    stroke: 'dotted',    // 'solid' (default), 'dashed' or 'dotted'
    color: '#ffffff'     // default: the entry's styles.color, then #18181b
}
```

📌 **Hinweis:**

- Setze `insetBorder` in den Widget-`data`, um alle Einträge mit Uhrzeit auf einmal zu ändern, z. B. `{ enabled: false }`, um die Linie überall auszublenden.
- Auf einem `timeEntry` oder Segment gesetzt, gilt es nur dort. Dort gesetzte Felder haben Vorrang vor der Widget-Ebene; nicht gesetzte Felder übernehmen deren Wert.
- Setzen Eintrag und eines seiner Segmente beide `insetBorder`, gilt für dieses Segment der Wert des Segments.
- 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.

**Stücke der Linie (`segments`)**

Die Linie lässt sich in Stücke teilen, zum Beispiel eine Farbe pro Person. Das ist nicht dasselbe wie die `segments` eines Eintrags (seine Phasen): Hier steht `segments` innerhalb von `insetBorder` und teilt nur die Linie.

```javascript
insetBorder: {
    color: '#18181b',    // Standard der Stücke
    align: 'start',      // 'start' (Standard), 'center' oder 'end': wo Stücke ohne Zeit sitzen, wenn sie die Linie nicht füllen
    segments: [
        // Mit Zeit sitzt das Stück dort, wo die Zeit liegt (Uhrzeiten am ersten Tag des Eintrags):
        { color: '#dc2626', label: 'Anna', timeFrom: 9 * 3600000, timeTo: 10.5 * 3600000 },
        // oder relativ zum Start des Eintrags; es wandert mit dem Eintrag:
        { color: '#2563eb', label: 'Ben', offset: 60 * 60000, duration: 90 * 60000 },
        // Ohne Zeit teilen sich die Stücke die Linie nach size:
        // { color: '#16a34a', label: 'Clara', size: '25%' }   // 'fraction' / 'auto' (Standard), '24px', '25%'
    ]
}
```

- `label` erscheint als Tooltip und wird von Screenreadern vorgelesen.
- Stücke mit Zeit dürfen sich überlappen: Wo zwei gleichzeitig aktiv sind, werden sie nebeneinander gezeichnet (bis zu drei Spuren) und der Text rückt ein. Zeit, die kein Stück abdeckt, bleibt leer.
- Hat irgendein Stück eine Zeit, werden Stücke ohne Zeit nicht gezeichnet. Ohne jede Zeit werden die Stücke nach `size` verteilt; sind die festen Größen länger als die Linie, schrumpfen alle im gleichen Verhältnis.
- `offset` zählt ab dem Start des angezeigten Stücks des Eintrags. Bei einem Eintrag, der durch `splits` geteilt ist, zählt jedes Stück ab seinem eigenen Start.
- Jedes Stück kann eigene `color` und `stroke` setzen; nicht gesetzte Felder übernehmen die der Linie.

### 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 🥳
<!-- /host -->


---

# Custom Calendar Grid

Source: https://www.arc-rider.com/docs/widgets/custom-calendar-grid


<!-- host:react -->
# CalendarGrid in React

Termine in einer Monatsübersicht anzeigen und Tage oder Einträge auswählen.

## AI Defaults (read first)

- Kopiere `examples/widgets/calendar_grid/calendar_grid-00-defaults.tsx` aus dem npm-Paket.
- Daten sind Epoch-Millisekunden des Tages um 00:00 UTC (`Date.UTC(2027, 0, 4)`), wie im Beispiel. `dateTo` ist **inklusive**. Gleiches `dateFrom` und `dateTo` = ein Tag. ISO-Strings werden nicht akzeptiert.
- Timed-Chip: `timeFrom` und `timeTo` als Millisekunden ab Mitternacht (`9 * 3600000` = 09:00). Ganztagsbalken: **beide Zeiten weglassen**. Dieselben Zeiten über mehrere Tage zeichnen einen Balken über diese Tage, bündig mit den Tagen; die Endzeit steht rechts. Bricht er in die nächste Woche um, zeigt die erste Zeile die Startzeit am rechten Rand des Starttags, die letzte Zeile wiederholt den Titel und zeigt die Endzeit.
- `dateSettings.month` ist 1–12. Den Monat nicht unter `weekdaySettings` setzen.
- `timeZoneBalance` verschiebt nur die Uhrzeit-Labels der Chips um ganze Stunden; `0` lassen, außer die Zeiten liegen in einer anderen Zone.
- `onEntryClick`, `onDayClick` und `onEntryDragSave` verdrahten. Einträge sind nur mit `draggable: true` verschiebbar. Dasselbe Flag erlaubt es, den linken oder rechten Rand eines Eintrags zu ziehen, um ihn zu kürzen oder zu verlängern. Persistiere **`endData`** aus `onEntryDragSave(entryIndex, startData, endData)` — nicht `startData` (sonst Snap-back).
- `title` ist ein String. JSX gehört in `customLayout`. Chip-Farbe: `styles.backgroundColor` und `styles.color` (`fontColor` fällt auf `color`).

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

<!-- react-example: calendar_grid-00-defaults.tsx -->
```tsx
import { useState } from "react";
import { ArcWidgetCalendarGrid } from "@arcrider/arcwidgets-react";
import type {
  ArcWidgetCalendarGridDailyEntryDragSavePayload,
  ArcWidgetCalendarGridEntryDragSavePayload,
  ArcWidgetCalendarGridTimeEntry,
} from "@arcrider/arcwidgets-react";

const day = (date: number) => Date.UTC(2027, 0, date);
const at = (hours: number, minutes = 0) => (hours * 60 + minutes) * 60000;

const initialEntries: ArcWidgetCalendarGridTimeEntry[] = [
  {
    title: "Team Offsite",
    dateFrom: day(4),
    dateTo: day(5),
    draggable: true,
  },
  {
    title: "Public Holiday",
    dateFrom: day(6),
    dateTo: day(6),
    draggable: true,
  },
  {
    title: "Team Meeting",
    dateFrom: day(4),
    dateTo: day(4),
    timeFrom: at(9),
    timeTo: at(10, 30),
    draggable: true,
  },
  {
    title: "Code Review",
    dateFrom: day(5),
    dateTo: day(5),
    timeFrom: at(10),
    timeTo: at(11),
    draggable: true,
  },
  {
    title: "Workshop",
    subtitle: "Room 2",
    dateFrom: day(5),
    dateTo: day(5),
    timeFrom: at(13, 30),
    timeTo: at(17),
    draggable: true,
  },
  {
    title: "Lunch",
    dateFrom: day(5),
    dateTo: day(5),
    timeFrom: at(12),
    timeTo: at(13),
    draggable: true,
  },
  {
    title: "Retro",
    dateFrom: day(5),
    dateTo: day(5),
    timeFrom: at(17),
    timeTo: at(18),
    draggable: true,
  },
  {
    title: "Sprint Planning",
    dateFrom: day(8),
    dateTo: day(8),
    timeFrom: at(9),
    timeTo: at(12),
    draggable: true,
  },
  // Timed, several days in one week. The bar lines up with Thursday–Saturday.
  // 15:00 is written at the right edge.
  {
    title: "Conference",
    dateFrom: day(7),
    dateTo: day(9),
    timeFrom: at(11),
    timeTo: at(15),
    draggable: true,
  },
  // Continues onto the next week row: that row repeats the title, and 11:00
  // is written at the right edge of the last piece only.
  {
    title: "Client Workshop",
    dateFrom: day(8),
    dateTo: day(11),
    timeFrom: at(16),
    timeTo: at(11),
    draggable: true,
  },
  {
    title: "Stand-up",
    dateFrom: day(18),
    dateTo: day(18),
    timeFrom: at(9),
    timeTo: at(9, 30),
    draggable: true,
  },
  {
    title: "Design Review",
    dateFrom: day(20),
    dateTo: day(20),
    timeFrom: at(14),
    timeTo: at(16),
    draggable: true,
  },
  {
    title: "All-Hands",
    dateFrom: day(22),
    dateTo: day(22),
    timeFrom: at(10),
    timeTo: at(11),
    draggable: true,
  },
  {
    title: "Office Closed",
    dateFrom: day(29),
    dateTo: day(29),
    draggable: true,
  },
  {
    title: "Release",
    subtitle: "v2.1",
    dateFrom: day(18),
    dateTo: day(22),
    timeFrom: at(10),
    timeTo: at(17),
    draggable: true,
  },
  {
    title: "Onboarding",
    subtitle: "Berlin office",
    dateFrom: day(25),
    dateTo: day(28),
    timeFrom: at(9),
    timeTo: at(16),
    draggable: true,
  },
];

export default function Example() {
  // Only the month and the entries are set; look and behavior are widget defaults.
  // A timed entry on one day is text with a stripe. The start time sits at the right edge.
  // Entries without times are light gray bars (Public Holiday, Team Offsite), with the same stripe.
  // A timed entry across days is the same kind of bar, lined up with the days. The end time sits at the right edge; if the bar wraps, its first row shows the start time at the right edge of the start day.
  //
  // Drag and save: `draggable: true` lets an entry be moved to another day. Its left and right
  // edge make it shorter or longer, from one day to several. The calendar only reports the
  // result. Write `endData` into the entry at `entryIndex`, then save it to your API.
  // If saving fails, put `startData` back. Without this step the entry jumps back on the next update.
  //
  // Day 5 has four timed entries. `maxTimeEntries.amount: 2` shows two and turns the rest into "+ 2 more".
  const [entries, setEntries] = useState(initialEntries);

  const persist = (
    entryIndex: number,
    endData:
      | ArcWidgetCalendarGridEntryDragSavePayload
      | ArcWidgetCalendarGridDailyEntryDragSavePayload,
  ) => {
    setEntries((current) =>
      current.map((entry, index) =>
        index === entryIndex ? { ...entry, ...endData } : entry,
      ),
    );
  };

  return (
    <ArcWidgetCalendarGrid
      data={{
        lang: "en",
        dateSettings: {
          month: 1,
          year: 2027,
          header: { title: {} },
          day: { maxTimeEntries: { amount: 2, suffix: "more" } },
        },
        timeEntries: entries,
      }}
      onEntryDragSave={(entryIndex, _startData, endData) =>
        persist(entryIndex, endData)
      }
      onDailyEntryDragSave={(entryIndex, _startData, endData) =>
        persist(entryIndex, endData)
      }
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

0-basierter Index des geklickten Termins in `data.timeEntries`. Feuert nur bei Einträgen mit `clickable: true`.

```typescript
onEntryClick?: (entryIndex: number) => void;
```

### onDayClick

Gewählter Tag als Epoch-Millisekunden um 00:00 UTC. Feuert nur mit `dateSettings.day.clickable: true`.

```typescript
onDayClick?: (dateMillis: number) => void;
```

### onEntryDragSave

Drag-Ende eines Termins mit Uhrzeit: `startData` (vorher) und `endData` (Drop-Ziel) — persistiere `endData`.

```typescript
onEntryDragSave?: (
	entryIndex: number,
	startData: ArcWidgetCalendarGridEntryDragSavePayload,
	endData: ArcWidgetCalendarGridEntryDragSavePayload
) => void;
```

### onDailyEntryDragSave

Drag-Ende eines ganztägigen Termins: `startData` und `endData` nur mit `dateFrom` / `dateTo` — persistiere `endData`.

```typescript
onDailyEntryDragSave?: (
	entryIndex: number,
	startData: ArcWidgetCalendarGridDailyEntryDragSavePayload,
	endData: ArcWidgetCalendarGridDailyEntryDragSavePayload
) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### width

Breite des Widgets, z. B. `"100%"`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### timeZoneBalance

Stundenversatz, der auf die Uhrzeit-Labels der Termine addiert wird, z. B. `-1`. Standard: `0`.

Typ: `number`.

### styles

Rahmen, Rasterlinien, Kopfzeilenfläche und Texttöne (`borders`, `borderColor`, `borderSize`, `borderRadius`, `backgroundColor`, `headerBackgroundColor`, `fontColor`, `mutedColor`, `subtleColor`).

Typ: `ArcWidgetCalendarGridStyles`.

### dateSettings

Sichtbarer Bereich, Kopfzeilen, Tageszellen und Markierungen. Setze `month` (`1`–`12`) und `year` für eine Monatsansicht über sechs Wochen, oder `startDate` mit `endDate` / `duration` (Tage) für einen freien Bereich. Ohne beides wird der aktuelle Monat gezeigt.

Typ: `ArcWidgetCalendarGridDateSettings`.

### lang

Locale für Wochentags- und Monatsnamen, z. B. `"en"`. Legt auch den ersten Wochentag fest: Sonntag bei `en-US`, `en-CA`, `ja`, `ko`, `zh-CN` und `zh-TW`, sonst Montag. Standard: `"de"`.

Typ: `string`.

### timeEntries

Termine mit Datumswerten, Uhrzeiten und Inhalten. Beide Zeiten weglassen für einen Ganztagsbalken.

Typ: `ArcWidgetCalendarGridTimeEntry[]`.

## Verhalten und Grenzen

- Für JSX in Terminen verwende `customLayout`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet.

- Datumswerte sind Epoch-Millisekunden des Tages um 00:00 UTC, z. B. `Date.UTC(2024, 10, 6)`; Uhrzeiten sind Millisekunden seit Tagesbeginn (`9 * 3600000` = 09:00). Beide Zeiten weglassen für einen Ganztagsbalken. 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.

- Drag: `draggable: true` auf dem Eintrag. Callback `onEntryDragSave(entryIndex, startData, endData)` / `onDailyEntryDragSave` — persistiere **`endData`** (`dateFrom`/`dateTo`/`timeFrom`/`timeTo`). `startData` ist der Stand vor dem Zug. Ohne `draggable: true` lässt sich der Eintrag nicht verschieben. Dasselbe Flag legt am echten Anfang und Ende des Eintrags eine Greifzone an: Ziehe daran, um den Eintrag tageweise zu kürzen oder zu verlängern, von einem Tag auf mehrere und zurück, auch über Wochenzeilen hinweg. Nur `dateFrom`/`dateTo` ändern sich, die Uhrzeiten bleiben. Schrumpft ein Eintrag mit Uhrzeit auf einen Tag und würde vor seinem Start enden, rückt `timeTo` knapp hinter `timeFrom`. Das Ergebnis kommt in denselben Callbacks wie beim Verschieben. Auf Touch-Geräten zuerst den Eintrag antippen, dann den Rand ziehen. Escape bricht ab.

- `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` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: calendar_grid -->
```typescript
export type ArcWidgetCalendarGridBorderLine =
	| boolean
	| {
			enabled?: boolean;
			color?: string;
			width?: string;
	  };

export interface ArcWidgetCalendarGridBorders {
	color?: string;
	width?: string;
	outer?: ArcWidgetCalendarGridBorderLine;
	columns?: ArcWidgetCalendarGridBorderLine;
	rows?: ArcWidgetCalendarGridBorderLine;
}

export interface ArcWidgetCalendarGridStyles {
	borders?: ArcWidgetCalendarGridBorders;
	borderColor?: string;
	borderSize?: string;
	borderRadius?: string;
	backgroundColor?: string;
	headerBackgroundColor?: string;
	fontColor?: string;
	mutedColor?: string;
	subtleColor?: string;
}

export interface ArcWidgetCalendarGridHeaderText {
	label?: string;
	fontSize?: string;
	fontColor?: string;
	fontWeight?: string | number;
	alignX?: 'left' | 'center' | 'right';
}

export interface ArcWidgetCalendarGridHeader {
	backgroundColor?: string;
	title?: ArcWidgetCalendarGridHeaderText;
	subtitle?: ArcWidgetCalendarGridHeaderText;
}

export interface ArcWidgetCalendarGridWeekdays {
	label?: string;
	backgroundColor?: string;
	alignX?: 'left' | 'center' | 'right';
	fontSize?: string;
	fontColor?: string;
	fontWeight?: string | number;
	padding?: string;
}

export interface ArcWidgetCalendarGridWeekNumber {
	fontColor?: string;
	fontWeight?: string | number;
	fontSize?: string;
}

export interface ArcWidgetCalendarGridWeek {
	show?: boolean;
	number?: ArcWidgetCalendarGridWeekNumber;
}

export interface ArcWidgetCalendarGridDayNumber {
	fontSize?: string;
	fontColor?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
	borderRadius?: string;
	border?: string;
}

export interface ArcWidgetCalendarGridMaxTimeEntries {
	amount?: number;
	suffix?: string;
}

export interface ArcWidgetCalendarGridDay {
	clickable?: boolean;
	height?: string;
	alignX?: 'left' | 'center' | 'right';
	backgroundColor?: string;
	hoverBackgroundColor?: string;
	padding?: string;
	number?: ArcWidgetCalendarGridDayNumber;
	maxTimeEntries?: ArcWidgetCalendarGridMaxTimeEntries;
}

export interface ArcWidgetCalendarGridHighlight {
	weekday?: number;
	date?: number;
	day?: ArcWidgetCalendarGridDay;
	color?: string;
}

export interface ArcWidgetCalendarGridDateSettings {
	month?: number;
	year?: number;
	startDate?: number;
	endDate?: number;
	duration?: number;
	header?: ArcWidgetCalendarGridHeader;
	weekdays?: ArcWidgetCalendarGridWeekdays;
	week?: ArcWidgetCalendarGridWeek;
	day?: ArcWidgetCalendarGridDay;
	highlights?: ArcWidgetCalendarGridHighlight[];
}

export type ArcWidgetCalendarGridEntryStyles = ArcWidgetCssProperties & {
	fontColor?: string;
};

export interface ArcWidgetCalendarGridTimeEntry {
	id?: string | number;
	title?: string;
	subtitle?: string;
	value?: string;
	customLayout?: ArcWidgetSlot;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	styles?: ArcWidgetCalendarGridEntryStyles;
	borderLeft?: string;
	clickable?: boolean;
	draggable?: boolean;
}

export interface ArcWidgetCalendarGridData {
	width?: string;
	height?: string;
	timeZoneBalance?: number;
	lang?: string;
	styles?: ArcWidgetCalendarGridStyles;
	dateSettings?: ArcWidgetCalendarGridDateSettings;
	timeEntries?: ArcWidgetCalendarGridTimeEntry[];
}

export interface ArcWidgetCalendarGridEntryDragSavePayload {
	dateFrom: number;
	dateTo: number;
	timeFrom: number;
	timeTo: number;
}

export interface ArcWidgetCalendarGridDailyEntryDragSavePayload {
	dateFrom: number;
	dateTo: number;
}

export interface ArcWidgetCalendarGridProps extends ArcReactWidgetProps<ArcWidgetCalendarGridData> {
	onEntryClick?: (entryIndex: number) => void;
	onDayClick?: (dateMillis: number) => void;
	onEntryDragSave?: (
		entryIndex: number,
		startData: ArcWidgetCalendarGridEntryDragSavePayload,
		endData: ArcWidgetCalendarGridEntryDragSavePayload
	) => void;
	onDailyEntryDragSave?: (
		entryIndex: number,
		startData: ArcWidgetCalendarGridDailyEntryDragSavePayload,
		endData: ArcWidgetCalendarGridDailyEntryDragSavePayload
	) => void;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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"
}
```
<!-- /host -->


---

# Custom Calendar Timeline

Source: https://www.arc-rider.com/docs/widgets/custom-calendar-timeline


<!-- host:react -->
# 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



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



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Ressourcenzeile und Termin des geklickten Balkens. `rowIndex` zählt die Zeilen der aufgefalteten `items`-Liste (Eltern vor ihren Kindern); `entryIndex` ist 0-basiert in den `timeEntries` dieser Zeile.

```typescript
onEntryClick?: (rowIndex: number, entryIndex: number) => void;
```

### onEntryDragSave

Drag-Ende: `startData` (vorher) und `endData` (Drop-Ziel) — persistiere `endData`; die Zielzeile ist `rowChange.row_index`. Im Tagesmodus kommen `dateFrom` / `dateTo`, im Zeitmodus `timeFrom` / `timeTo`.

```typescript
onEntryDragSave?: (
	rowIndex: number,
	entryIndex: number,
	startData: ArcWidgetCalendarTimelineEntryDragSavePayload,
	rowChange: ArcWidgetCalendarTimelineRowChangePayload,
	endData: ArcWidgetCalendarTimelineEntryDragSavePayload
) => void;
```

### onLabelClick

Ressourcenzeile und 0-basierte Beschriftungsspalte der geklickten Zelle. Feuert nur bei Zellen mit `clickable: true`.

```typescript
onLabelClick?: (rowIndex: number, columnIndex: number) => void;
```

### onGhostClick

Ressourcenzeile und Spaltenbeginn des geklickten Plus-Buttons: Epoch-Millisekunden im Tagesmodus, Millisekunden ab Mitternacht im Zeitmodus.

```typescript
onGhostClick?: (rowIndex: number, columnValue: number) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### mode

Spaltentyp: `"day"` zeigt Tage, `"time"` die Stunden eines Tages. Standard: `"time"`, wenn `timeSettings` gesetzt ist, sonst `"day"`.

Typ: `'day' | 'time'`.

### width

Breite des Widgets, z. B. `"100%"`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"320px"`. `"auto"` wächst mit den Zeilen; Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### minHeight / maxHeight

Grenzen für `height: "auto"`, z. B. `"600px"`; über `maxHeight` scrollt die Timeline.

Typ: `string`.

### timeZoneBalance

Stundenversatz, der auf die Uhrzeit-Labels der Balken addiert wird, z. B. `-1`. Standard: `0`.

Typ: `number`.

### weekStart

Erster Tag der Standardwoche, wenn `dateSettings.startDate` fehlt: `1` = Montag … `7` = Sonntag. Standard: `1`.

Typ: `number`.

### dateSettings

Sichtbarer Bereich, Kopfzeilen und Markierungen. `startDate` (Epoch-Millisekunden) ist der erste sichtbare Tag; Termindaten werden relativ dazu platziert. `endDate` (exklusiv) oder `duration` (Tage, Standard `7`) legt die Länge fest.

Typ: `ArcWidgetCalendarTimelineDateSettings`.

### timeSettings

Sichtbare Stunden im Zeitmodus, in **Stunden**: `startTime` (Standard `0`), `amount` pro Spalte (Standard `1`) und `duration` (Standard `12`).

Typ: `ArcWidgetCalendarTimelineTimeSettings`.

### columns

Linke Beschriftungsspalten der Ressourcen. Ohne Angabe wird eine Spalte mit `labelWidth` gezeigt.

Typ: `ArcWidgetCalendarTimelineColumn[]`.

### labelWidth

Breite der Beschriftungsspalten ohne eigenes `width`. Standard: `"120px"`.

Typ: `string`.

### items

Ressourcenzeilen mit Beschriftungszellen, `timeEntries`, Markierungen, Plus-Button (`ghost`) und Unterzeilen (`items`).

Typ: `ArcWidgetCalendarTimelineItem[]`.

### maxItemDepth

Maximale Verschachtelungstiefe von `items`; `0` zeigt nur die oberste Ebene. Standardmäßig ohne Grenze.

Typ: `number`.

### collapsible

Macht Elternzeilen über ihre erste Beschriftungszelle einklappbar. Standard: aus.

Typ: `ArcWidgetCalendarTimelineCollapsible`.

### dayWidth

Mindestbreite einer Tagesspalte, z. B. `"120px"`.

Typ: `string`.

### columnWidth

Mindestbreite einer Tages- oder Stundenspalte; hat Vorrang vor `dayWidth`.

Typ: `string`.

### rowHeight

Mindesthöhe einer Ressourcenzeile. Standard: `"80px"`.

Typ: `string`.

### currentTime

`true` zeigt eine Linie für die aktuelle Uhrzeit; ein Farbstring setzt zusätzlich ihre Farbe. Standard: `false`.

Typ: `boolean | string`.

### zoomSettings

Zoom der Tagesbreite: Grenzen, Schrittweite, Speichern und die Plus-/Minus-Buttons. Zoom ist standardmäßig an.

Typ: `ArcWidgetCalendarTimelineZoomSettings`.

### lang

Locale für Datumsbeschriftungen. Standard: `"de"`.

Typ: `string`.

### styles

Rahmen, Rasterlinien, Flächen, Texttöne und Tagesstreifen.

Typ: `ArcWidgetCalendarTimelineStyles`.

## Verhalten und Grenzen

- Für JSX in Terminen verwende `customLayout` oder `tooltip.value`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet. Beschriftungszellen und der Kopf-Titel akzeptieren HTML-Strings oder Widget-Deskriptoren, kein JSX.

- Datumswerte sind Epoch-Millisekunden in derselben Zeitbasis wie `dateSettings.startDate`; Uhrzeiten sind Millisekunden seit Tagesbeginn (`9 * 3600000` = 09:00). 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.

- Drag: `draggable: true` auf dem Eintrag. Callback `onEntryDragSave(rowIndex, entryIndex, startData, rowChange, endData)` — persistiere **`endData`** und die Zielzeile aus `rowChange.row_index`. Ohne `draggable: true` lässt sich der Eintrag nicht verschieben.

- `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`, `ArcWidgetCssStyles`, `ArcNestedWidgetDescriptor` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: calendar_timeline -->
```typescript
export type ArcWidgetCalendarTimelineBorderLine =
	| boolean
	| {
			enabled?: boolean;
			color?: string;
			width?: string;
	  };

export interface ArcWidgetCalendarTimelineBorders {
	color?: string;
	width?: string;
	outer?: ArcWidgetCalendarTimelineBorderLine;
	columns?: ArcWidgetCalendarTimelineBorderLine;
	rows?: ArcWidgetCalendarTimelineBorderLine;
}

export interface ArcWidgetCalendarTimelineDayStripes {
	enabled?: boolean;
	odd?: string;
	even?: string;
}

export interface ArcWidgetCalendarTimelineStyles {
	borders?: ArcWidgetCalendarTimelineBorders;
	borderColor?: string;
	borderSize?: string;
	borderRadius?: string;
	backgroundColor?: string;
	headerBackgroundColor?: string;
	groupBackgroundColor?: string;
	rowBackgroundColor?: string;
	fontColor?: string;
	mutedColor?: string;
	subtleColor?: string;
	fontSize?: string;
	dayStripes?: boolean | ArcWidgetCalendarTimelineDayStripes;
}

export interface ArcWidgetCalendarTimelineTitleSlot {
	value?: string | ArcNestedWidgetDescriptor;
	customLayout?: string | ArcNestedWidgetDescriptor;
	alignX?: 'left' | 'center' | 'right';
	fontSize?: string;
	fontColor?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
}

export interface ArcWidgetCalendarTimelineLabelBreakpoint {
	below: number;
	label: string;
}

export interface ArcWidgetCalendarTimelineDaysHeader {
	visible?: boolean;
	label?: string;
	labelBreakpoints?: ArcWidgetCalendarTimelineLabelBreakpoint[];
	hideBelow?: number;
	compactRanges?: boolean;
	monthCompactBelow?: number;
	backgroundColor?: string;
	fontColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
	alignX?: 'left' | 'center' | 'right';
	sticky?: 'left';
	stickyPadding?: number | string;
}

export interface ArcWidgetCalendarTimelineGroupHighlight {
	month?: number;
	week?: number;
	color?: string;
}

export interface ArcWidgetCalendarTimelineGroupHeader {
	visible?: boolean;
	label?: string;
	hideBelow?: number;
	backgroundColor?: string;
	fontColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
	alignX?: 'left' | 'center' | 'right';
	sticky?: 'left';
	stickyPadding?: number | string;
	highlights?: ArcWidgetCalendarTimelineGroupHighlight[];
}

export interface ArcWidgetCalendarTimelineHeader {
	backgroundColor?: string;
	fontColor?: string;
	title?: string | ArcNestedWidgetDescriptor | ArcWidgetCalendarTimelineTitleSlot;
	days?: ArcWidgetCalendarTimelineDaysHeader;
	months?: ArcWidgetCalendarTimelineGroupHeader;
	weeks?: ArcWidgetCalendarTimelineGroupHeader;
}

export interface ArcWidgetCalendarTimelineHighlightStyles {
	backgroundColor?: string;
	borderColor?: string;
	borderSize?: string;
	borders?: Pick<ArcWidgetCalendarTimelineBorders, 'color' | 'width' | 'columns' | 'rows'>;
}

export interface ArcWidgetCalendarTimelineHighlight {
	date?: number | string;
	weekday?: number;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	hour?: number;
	color?: string;
	styles?: ArcWidgetCalendarTimelineHighlightStyles;
}

export interface ArcWidgetCalendarTimelineDateHighlight extends ArcWidgetCalendarTimelineHighlight {
	applyToRows?: boolean;
	title?: {
		label?: string;
	};
}

export interface ArcWidgetCalendarTimelineDateSettings {
	startDate?: number;
	endDate?: number;
	duration?: number;
	header?: ArcWidgetCalendarTimelineHeader;
	highlights?: ArcWidgetCalendarTimelineDateHighlight[];
}

export interface ArcWidgetCalendarTimelineTimeSettings {
	startTime?: number;
	amount?: number;
	duration?: number;
}

export interface ArcWidgetCalendarTimelineColumn {
	title?: string;
	subtitle?: string;
	width?: string;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom';
	fontSize?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
	fontColor?: string;
}

export interface ArcWidgetCalendarTimelineItemColumn {
	title?: string;
	subtitle?: string;
	customLayout?: string | ArcNestedWidgetDescriptor;
	clickable?: boolean;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom';
	fontSize?: string;
	fontWeight?: string | number;
}

export interface ArcWidgetCalendarTimelineItemStyles {
	backgroundColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
}

export interface ArcWidgetCalendarTimelineGhost {
	title?: string;
	clickable?: boolean;
	position?: 'bottomRight' | 'bottomLeft' | 'topRight' | 'topLeft' | 'timeEntry';
	styles?: ArcWidgetCssStyles;
}

export interface ArcWidgetCalendarTimelineEntryLabel {
	value?: string | number;
	width?: 'fraction' | 'auto' | (string & {});
}

export interface ArcWidgetCalendarTimelineTooltipStyles {
	backgroundColor?: string;
	color?: string;
	borderRadius?: string;
	borderSize?: string;
	borderColor?: string;
	padding?: string;
	fontSize?: string;
	boxShadow?: string;
}

export interface ArcWidgetCalendarTimelineTooltip {
	value?: ArcWidgetSlot;
	position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
	width?: string;
	maxWidth?: string;
	maxHeight?: string;
	styles?: ArcWidgetCalendarTimelineTooltipStyles;
}

export type ArcWidgetCalendarTimelineEntryStyles = ArcWidgetCssProperties;

export interface ArcWidgetCalendarTimelineTimeEntry {
	id?: string | number;
	title?: string | ArcWidgetCalendarTimelineEntryLabel;
	subtitle?: string | ArcWidgetCalendarTimelineEntryLabel;
	direction?: 'vertical' | 'horizontal';
	value?: string;
	customLayout?: ArcWidgetSlot;
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
	styles?: ArcWidgetCalendarTimelineEntryStyles;
	clickable?: boolean;
	draggable?: boolean;
	tooltip?: ArcWidgetCalendarTimelineTooltip;
}

export interface ArcWidgetCalendarTimelineItem {
	id?: string | number;
	title?: string;
	subtitle?: string;
	styles?: ArcWidgetCalendarTimelineItemStyles;
	fontSize?: string;
	fontWeight?: string | number;
	columns?: ArcWidgetCalendarTimelineItemColumn[];
	timeEntries?: ArcWidgetCalendarTimelineTimeEntry[];
	highlights?: ArcWidgetCalendarTimelineHighlight[];
	ghost?: ArcWidgetCalendarTimelineGhost;
	items?: ArcWidgetCalendarTimelineItem[];
}

export interface ArcWidgetCalendarTimelineCollapsible {
	enabled?: boolean;
	iconCollapse?: string;
	iconExpand?: string;
	iconPosition?: 'left' | 'right';
}

export interface ArcWidgetCalendarTimelineZoomControls {
	enabled?: boolean;
	position?: 'bottomRight';
}

export interface ArcWidgetCalendarTimelineZoomSettings {
	enabled?: boolean;
	defaultDayWidth?: number | string;
	minDayWidth?: number | string;
	maxDayWidth?: number | string;
	step?: number | string;
	persist?: boolean;
	controls?: ArcWidgetCalendarTimelineZoomControls;
}

export interface ArcWidgetCalendarTimelineData {
	mode?: 'day' | 'time';
	width?: string;
	height?: string;
	minHeight?: string;
	maxHeight?: string;
	lang?: string;
	timeZoneBalance?: number;
	weekStart?: number;
	dateSettings?: ArcWidgetCalendarTimelineDateSettings;
	timeSettings?: ArcWidgetCalendarTimelineTimeSettings;
	columns?: ArcWidgetCalendarTimelineColumn[];
	labelWidth?: string;
	items?: ArcWidgetCalendarTimelineItem[];
	maxItemDepth?: number;
	collapsible?: ArcWidgetCalendarTimelineCollapsible;
	dayWidth?: string;
	columnWidth?: string;
	rowHeight?: string;
	currentTime?: boolean | string;
	zoomSettings?: ArcWidgetCalendarTimelineZoomSettings;
	styles?: ArcWidgetCalendarTimelineStyles;
}

export interface ArcWidgetCalendarTimelineEntryDragSavePayload {
	dateFrom?: number;
	dateTo?: number;
	timeFrom?: number;
	timeTo?: number;
}

export interface ArcWidgetCalendarTimelineRowChangePayload {
	start_row_index: number;
	row_index: number;
}

export interface ArcWidgetCalendarTimelineProps extends ArcReactWidgetProps<ArcWidgetCalendarTimelineData> {
	onEntryClick?: (rowIndex: number, entryIndex: number) => void;
	onEntryDragSave?: (
		rowIndex: number,
		entryIndex: number,
		startData: ArcWidgetCalendarTimelineEntryDragSavePayload,
		rowChange: ArcWidgetCalendarTimelineRowChangePayload,
		endData: ArcWidgetCalendarTimelineEntryDragSavePayload
	) => void;
	onLabelClick?: (rowIndex: number, columnIndex: number) => void;
	onGhostClick?: (rowIndex: number, columnValue: number) => void;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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("<strong>Wartung Anlage Nord</strong><br>Dauer: 3 Tage<br>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("<div style='font-weight:600;color:#0f172a'>Termin-Details</div>")
                },
                {
                    width: "100%",
                    value: html("<div style='color:#334155;font-size:12px'>Kunde: Schmidt AG<br>Thema: Angebot Q3</div>")
                },
                {
                    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 🥳
<!-- /host -->


---

# Custom Dev Tools

Source: https://www.arc-rider.com/docs/widgets/custom-dev-tools


<!-- host:react -->
# 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



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



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Ein Footer-Button mit `clickable: true` wurde angeklickt. Liefert seinen nullbasierten Index in `footerButtons`.

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

Das Panel: `visible` blendet es ein (Standard `false`), `maxErrors` begrenzt die Liste (Standard `50`), `debug` ergänzt eigene Key/Value-Zeilen (Objekte erscheinen als JSON), `footerButtons` ergänzt Buttons mit `title` und `clickable`.

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.

- Nur als `clickable` markierte Footer-Buttons lösen `onFooterClick` aus. Button-Titel und Debug-Werte werden als reiner Text angezeigt.

- Die Position des Panels wird nach dem Verschieben je Instanz gespeichert. Zeige nur Diagnosedaten, die für die jeweiligen Nutzer bestimmt sind.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: dev_tools -->
```typescript
export interface ArcWidgetDevToolsFooterButton {
	title?: string;
	clickable?: boolean;
}

export interface ArcWidgetDevToolsDebug {
	[key: string]: unknown;
}

export interface ArcWidgetDevToolsErrorPanel {
	visible?: boolean;
	maxErrors?: number;
	debug?: ArcWidgetDevToolsDebug;
	footerButtons?: ArcWidgetDevToolsFooterButton[];
}

export interface ArcWidgetDevToolsData {
	errorPanel?: ArcWidgetDevToolsErrorPanel;
}

export interface ArcWidgetDevToolsProps extends ArcReactWidgetProps<ArcWidgetDevToolsData> {
	onFooterClick?: (index: number) => void;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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 }`.
<!-- /host -->


---

# Custom Drawing

Source: https://www.arc-rider.com/docs/widgets/custom-drawing


<!-- host:react -->
# 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

<!-- react-example: drawing-00-defaults.tsx -->
```tsx
import { ArcWidgetDrawing } from '@arcrider/arcwidgets-react';

export default function Example() {
  // Only required fields are set; everything else is the widget default.
  return (
    <ArcWidgetDrawing
      data={{
        height: '480px',
        artboard: { width: 600, height: 400 },
        shapes: [
          {
            id: 1,
            shapeDataValue: {
              type: 'rect',
              x: 60,
              y: 60,
              width: 200,
              height: 120,
            },
          },
          {
            id: 2,
            shapeDataValue: { type: 'circle', cx: 420, cy: 160, r: 70 },
          },
          {
            id: 3,
            shapeDataValue: {
              type: 'polyline',
              points: '80,300 200,340 320,280 460,330',
            },
          },
          {
            id: 4,
            shapeDataValue: {
              type: 'polygon',
              points: '380,240 470,260 500,330 420,370 360,320',
              fill: 'rgba(0, 120, 255, 0.2)',
            },
          },
          {
            id: 5,
            shapeDataValue: {
              type: 'text',
              x: 60,
              y: 200,
              text: 'Floor plan',
              fontSize: 20,
              fontWeight: 'bold',
            },
          },
        ],
      }}
    />
  );
}
```

## Features ausprobieren

### Freihand zeichnen und Formen übernehmen

Zeichne eigene Formen. Erstellen und Bearbeiten aktualisieren den React-State.



### Markierungen speichern und wiederherstellen

Wähle eine Markierung aus und teste die lokale Speicherung.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Eine Form wurde gezeichnet oder ein Sticker platziert. Das zweite Argument ist ein Completion-Objekt: Setze dessen `promise` auf ein Promise mit der neuen ID.

```typescript
onShapeCreate?: (payload: ArcWidgetDrawingShapeCreatePayload, completion: ArcWidgetDrawingShapeCreateCompletion) => void;
```

### onShapeUpdate

Eine gespeicherte Form wurde mit dem Verschieben-Werkzeug gezogen oder angeklickt und losgelassen. Liefert `shape_id`, die neue Geometrie und mit `dataBag` den ganzen Topf.

```typescript
onShapeUpdate?: (payload: ArcWidgetDrawingShapeUpdatePayload) => void;
```

### onShapeActivate

Eine Form mit `clickable: true` wurde angeklickt. Liefert ihre `shape_id`.

```typescript
onShapeActivate?: (payload: ArcWidgetDrawingShapeActivatePayload) => void;
```

### onExport

Ein Export mit Ziel `field` ist fertig. Liefert das Format und die Datei als Data-URL.

```typescript
onExport?: (payload: ArcWidgetDrawingExportPayload) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen in verschachtelten Objekten sind Zahlen in Pixeln; Widget-Größen sind CSS-Strings.

### artboard

Pflicht. Zeichen- und Exportbereich in Pixeln.

Typ: `ArcWidgetDrawingArtboard` (`{ width: number; height: number }`).

### shapes

Pflicht. Formen mit stabiler `id` und Geometrie in `shapeDataValue` (Objekt oder JSON-String). Für eine leere Fläche `[]` übergeben. Optional je Form: `movable`, `scalable`, `clickable`, `stickerUID`, `label`, `placeholders`, `export`, `tooltip`, `sidebarItem`.

Typ: `ArcWidgetDrawingShape[]`.

### height

Höhe des Widgets, z. B. `"700px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### width

Breite des Widgets, z. B. `"100%"`.

Typ: `string`.

### canvas

Verschiebbare Arbeitsfläche um das Artboard in Pixeln: `width` / `height` oder `offsetX` / `offsetY` als zusätzlicher Rand je Seite. Ohne Angabe lässt sich die Ansicht etwa eine Viewport-Größe über das Artboard hinaus bewegen.

Typ: `ArcWidgetDrawingCanvas`.

### zooming

Start-Zoom (`default`, 1), Grenzen (`min` 0,1, `max` unbegrenzt), Schrittweite der Buttons (`step`, 0,1) und Geschwindigkeit für Strg + Mausrad (`panSpeed`, 0,002).

Typ: `ArcWidgetDrawingZooming`.

### drawingSettings

Linie für neue Freihandlinien, Rechtecke, Kreise und Polygone: `strokeColor` (Standard `black`) und `strokeWidth` in Bildschirmpixeln (Standard `1`). `polygon.fillColor` setzt die Füllung neuer Polygone (Standard: keine Füllung). `text` enthält die Standardwerte für neuen Text: `color` (Standard `black`), `fontSize` (Standard `16`), `fontWeight` (Standard `normal`) und `fontFamily` (Standard `Arial, Helvetica, sans-serif`).

Typ: `ArcWidgetDrawingSettings`.

### tools

`useMoveTool: true` lässt Formen nur mit dem Verschieben-Werkzeug greifen; in den anderen Werkzeugen erzeugt ein Klick auf eine Form neuen Inhalt.

Typ: `ArcWidgetDrawingTools`.

### create

`enabled: false` deaktiviert Zeichenwerkzeuge und Sticker. Verschieben der Ansicht, Zoomen, Verschieben von Formen und Klicks funktionieren weiter. Standard: `true`.

Typ: `ArcWidgetDrawingCreate`.

### stickerTypes

Sticker zum Platzieren: `uid`, `image`, `width`, `height` sowie optional `icon`, `label`, `originX` / `originY`, `default`, `labelPlaceholder`, `defaultLabel`, `defaultPlaceholders`.

Typ: `ArcWidgetDrawingStickerType[]`.

### toolbarSettings

Reihenfolge und Gruppierung der Toolbar-Buttons in `top` und `bottom`. Einträge sind Werkzeug-IDs (`"move"`, `"draw"`, `"rect"`, `"circle"`, `"polygon"`, `"text"`, `"image"`, `"export"`), `"stickers"`, `{ tool, icon }`, `{ sticker, icon }` oder in `top` eine Gruppe `{ group, label, icon, items }`. Nicht aufgeführte Buttons werden nicht angezeigt.

Typ: `ArcWidgetDrawingToolbarSettings`.

### exportSettings

Export-Button und Formate. `allowedTypes` ist Pflicht und listet `"jpg"`, `"png"`, `"svg"` oder Einstellungen je Format. `target: "field"` übergibt die Datei an `onExport`; `"file"` (Standard) startet den Download.

Typ: `ArcWidgetDrawingExportSettings`.

### dataBag

Liest die Geometrie aus einem `key` eines JSON-Topfs in `shapeDataValue`, damit deine übrigen Keys erhalten bleiben. `onShapeUpdate` liefert den ganzen Topf als `bag`.

Typ: `ArcWidgetDrawingDataBag`.

### rightSideContent

Seitenleiste rechts neben der Zeichenfläche mit `header`, `content` (`showShapeLayers` oder `value`) und `footer`. Ohne Angabe ausgeblendet; `show: false` blendet sie aus.

Typ: `ArcWidgetDrawingSidebar`.

## Verhalten und Grenzen

- Jede Form braucht eine stabile `id` und `shapeDataValue` als Objekt oder serialisierten JSON-String; Formen ohne `shapeDataValue` werden nicht gezeichnet.

- 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 Geometrie in `shape_data_value`. Ersetze die passende Form unveränderlich in deinem State.

- Für `onExport` ist `exportSettings.allowedTypes: [{ format: "png", target: "field" }]` nötig. `target: "field"` übergibt das Bild als Data-URL an `onExport`; `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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: drawing -->
```typescript
export type ArcWidgetDrawingShapeType = 'rect' | 'circle' | 'polyline' | 'polygon' | 'text' | 'image' | 'sticker';

export interface ArcWidgetDrawingShapeData {
	type: ArcWidgetDrawingShapeType;
	x?: number;
	y?: number;
	width?: number;
	height?: number;
	cx?: number;
	cy?: number;
	r?: number;
	points?: string;
	href?: string;
	stickerUID?: string;
	stroke?: string;
	strokeWidth?: number;
	fill?: string;
	text?: string;
	fontSize?: number;
	fontWeight?: string | number;
	fontFamily?: string;
	[key: string]: unknown;
}

export type ArcWidgetDrawingTooltipStyles = ArcWidgetCssProperties;

export interface ArcWidgetDrawingTooltip {
	content?: ArcWidgetSlot;
	width?: number | string;
	height?: number | string;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom';
	offsetX?: number;
	offsetY?: number;
	styles?: ArcWidgetDrawingTooltipStyles;
}

export interface ArcWidgetDrawingSidebarItem {
	header?: ArcWidgetSlot;
	content?: ArcWidgetSlot;
	hide?: boolean;
}

export interface ArcWidgetDrawingShape {
	id: string | number;
	shapeDataValue?: ArcWidgetDrawingShapeData | string;
	movable?: boolean;
	scalable?: boolean;
	clickable?: boolean;
	stickerUID?: string;
	label?: string | number;
	placeholders?: Record<string, string | number>;
	export?: boolean;
	tooltip?: ArcWidgetDrawingTooltip;
	sidebarItem?: ArcWidgetDrawingSidebarItem;
}

export type ArcWidgetDrawingIcon = string | ArcNestedWidgetDescriptor;

export interface ArcWidgetDrawingStickerLabel {
	value: string;
	visible?: boolean;
	fontColor?: string;
	fontSize?: number | string;
	maxWidth?: number | string;
}

export interface ArcWidgetDrawingStickerType {
	uid: string;
	image: string;
	icon?: ArcWidgetDrawingIcon;
	label?: string | ArcWidgetDrawingStickerLabel;
	width: number;
	height: number;
	originX?: number;
	originY?: number;
	default?: boolean;
	labelPlaceholder?: string;
	defaultLabel?: string | number;
	defaultPlaceholders?: Record<string, string | number>;
}

export type ArcWidgetDrawingTool = 'move' | 'draw' | 'rect' | 'circle' | 'polygon' | 'text' | 'image' | 'export';

export type ArcWidgetDrawingToolbarItem =
	| ArcWidgetDrawingTool
	| 'stickers'
	| {
			tool: ArcWidgetDrawingTool;
			icon?: ArcWidgetDrawingIcon;
	  }
	| {
			sticker: string;
			icon?: ArcWidgetDrawingIcon;
	  };

export interface ArcWidgetDrawingToolbarGroup {
	group: string;
	label?: string;
	icon?: ArcWidgetDrawingIcon;
	items: ArcWidgetDrawingToolbarItem[];
}

export interface ArcWidgetDrawingToolbarSettings {
	top?: (ArcWidgetDrawingToolbarItem | ArcWidgetDrawingToolbarGroup)[];
	bottom?: ArcWidgetDrawingToolbarItem[];
}

export type ArcWidgetDrawingExportFormat = 'jpg' | 'png' | 'svg' | 'pdf';

export type ArcWidgetDrawingExportTarget = 'file' | 'field';

export interface ArcWidgetDrawingExportType {
	format: ArcWidgetDrawingExportFormat;
	target?: ArcWidgetDrawingExportTarget;
	mergeFile?: boolean;
	apiKey?: string;
	autoExport?: boolean;
	autoExportDelay?: number;
}

export interface ArcWidgetDrawingExportSettings {
	allowedTypes: (ArcWidgetDrawingExportFormat | ArcWidgetDrawingExportType)[];
	target?: ArcWidgetDrawingExportTarget;
	apiKey?: string;
	mergeFile?: string;
	iconColor?: string;
}

export interface ArcWidgetDrawingArtboard {
	width: number;
	height: number;
}

export interface ArcWidgetDrawingCanvas {
	width?: number;
	height?: number;
	offsetX?: number;
	offsetY?: number;
}

export interface ArcWidgetDrawingZooming {
	default?: number;
	min?: number;
	max?: number;
	step?: number;
	panSpeed?: number;
}

export interface ArcWidgetDrawingPolygonSettings {
	fillColor?: string;
}

export interface ArcWidgetDrawingTextSettings {
	color?: string;
	fontSize?: number;
	fontWeight?: string | number;
	fontFamily?: string;
}

export interface ArcWidgetDrawingSettings {
	strokeColor?: string;
	strokeWidth?: number;
	polygon?: ArcWidgetDrawingPolygonSettings;
	text?: ArcWidgetDrawingTextSettings;
}

export interface ArcWidgetDrawingTools {
	useMoveTool?: boolean;
}

export interface ArcWidgetDrawingCreate {
	enabled?: boolean;
}

export interface ArcWidgetDrawingDataBag {
	key: string;
	encoding?: 'raw' | 'urlEncoded';
}

export interface ArcWidgetDrawingSidebarContent {
	showShapeLayers?: boolean;
	value?: ArcWidgetSlot;
}

export interface ArcWidgetDrawingSidebar {
	show?: boolean;
	width?: string;
	header?: ArcWidgetSlot;
	content?: ArcWidgetDrawingSidebarContent;
	footer?: ArcWidgetSlot;
}

export interface ArcWidgetDrawingData {
	artboard: ArcWidgetDrawingArtboard;
	shapes: ArcWidgetDrawingShape[];
	height?: string;
	width?: string;
	canvas?: ArcWidgetDrawingCanvas;
	zooming?: ArcWidgetDrawingZooming;
	drawingSettings?: ArcWidgetDrawingSettings;
	tools?: ArcWidgetDrawingTools;
	create?: ArcWidgetDrawingCreate;
	stickerTypes?: ArcWidgetDrawingStickerType[];
	toolbarSettings?: ArcWidgetDrawingToolbarSettings;
	exportSettings?: ArcWidgetDrawingExportSettings;
	dataBag?: ArcWidgetDrawingDataBag;
	rightSideContent?: ArcWidgetDrawingSidebar;
}

export interface ArcWidgetDrawingShapeCreatePayload {
	shape_data_value: ArcWidgetDrawingShapeData;
	sticker_uid: string | null;
}

export interface ArcWidgetDrawingShapeCreateCompletion {
	promise?: Promise<string | number>;
}

export interface ArcWidgetDrawingShapeUpdatePayload {
	shape_id: string | number;
	shape_data_value: ArcWidgetDrawingShapeData;
	bag?: Record<string, unknown>;
}

export interface ArcWidgetDrawingShapeActivatePayload {
	shape_id: string | number;
}

export interface ArcWidgetDrawingExportPayload {
	format: ArcWidgetDrawingExportFormat;
	base64: string;
}

export interface ArcWidgetDrawingProps extends ArcReactWidgetProps<ArcWidgetDrawingData> {
	onShapeCreate?: (payload: ArcWidgetDrawingShapeCreatePayload, completion: ArcWidgetDrawingShapeCreateCompletion) => void;
	onShapeUpdate?: (payload: ArcWidgetDrawingShapeUpdatePayload) => void;
	onShapeActivate?: (payload: ArcWidgetDrawingShapeActivatePayload) => void;
	onExport?: (payload: ArcWidgetDrawingExportPayload) => void;
}
```

## 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)
<!-- /host -->

<!-- host:ninox -->
# 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

<iframe src="https://www.youtube.com/embed/sOn_9zeffCI?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>Das **Custom Drawing Widget** ermöglicht es, beliebige Bilder (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"
                    }],
                target: "file",
                recordId: Nr,
                fieldId: fieldId("Tabelle", "Feld für den Export"),
            },
            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, Polygone, Text, 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) und wohin die Datei gespeichert werden soll.


<figure><table><tbody><tr><th>Feld

</th><th>Beschreibung

</th></tr><tr><td>`allowedTypes`

</td><td>Liste der erlaubten Exportformate. Du kannst `"jpg"`, `"png"` und `"svg"` angeben.

</td></tr><tr><td>`target`

</td><td>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.

</td></tr><tr><td>`recordId`

</td><td>Gibt den Datensatz an, in den exportiert werden soll (nur bei `target: "field"` erforderlich).

</td></tr><tr><td>`fieldId`

</td><td>Definiert das genaue Feld im Datensatz, in das die exportierte Datei geschrieben wird.

</td></tr></tbody></table></figure>

#### 🔄 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: \"png\",
        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, Kreise, Polygone oder Text, 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.
- `polygon.fillColor`: Füllfarbe neuer Polygone, z. B. `rgba(0, 120, 255, 0.2)`. Ohne Angabe haben Polygone keine Füllung.
- `text.color`: Textfarbe für neuen Text (Standard `black`).
- `text.fontSize`: Schriftgröße neuer Texte in Canvas-Pixeln (Standard `16`).
- `text.fontWeight`: Schriftstärke, z. B. `bold` oder `600` (Standard `normal`).
- `text.fontFamily`: CSS-Schriftfamilie (Standard `Arial, Helvetica, sans-serif`).

💡 **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) |

#### Polygon- und Text-Werkzeug

Beide Werkzeuge sind nicht in der Standard-Toolbar. Mit `"polygon"` und `"text"` in `toolbarSettings` blendest du sie ein.

- `"polygon"`: Jede Ecke per Klick setzen. Beenden mit Klick auf die erste Ecke (ab drei Ecken), Doppelklick oder Enter; Esc bricht ab, Rücktaste entfernt die letzte Ecke.
- `"text"`: Dorthin klicken, wo der Text beginnen soll, tippen und mit Enter bestätigen (Umschalt+Enter = neue Zeile). Esc bricht ab. Doppelklick auf einen vorhandenen Text bearbeitet ihn.

**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. Unterstützte `type`-Werte: `rect`, `circle`, `polyline`, `polygon` (geschlossene Fläche mit `points` und optional `fill`), `text` (`x`, `y`, `text`, optional `fontSize`, `fontWeight`, `fontFamily`; `fill` ist die Textfarbe), `image` und `sticker`.
- `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:</p><ul><li data-preset-tag="p"><p>`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)

</li></ul>

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

<h5>🔍 `content`-Block im Detail:</h5>- `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.
<!-- /host -->

<!-- host:vue -->
# 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

<iframe src="https://www.youtube.com/embed/sOn_9zeffCI?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>Das **Custom Drawing Widget** ermöglicht es, beliebige Bilder (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"
                    }],
                target: "file",
                recordId: Nr,
                fieldId: fieldId("Tabelle", "Feld für den Export"),
            },
            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, Polygone, Text, 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) und wohin die Datei gespeichert werden soll.


<figure><table><tbody><tr><th>Feld

</th><th>Beschreibung

</th></tr><tr><td>`allowedTypes`

</td><td>Liste der erlaubten Exportformate. Du kannst `"jpg"`, `"png"` und `"svg"` angeben.

</td></tr><tr><td>`target`

</td><td>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.

</td></tr><tr><td>`recordId`

</td><td>Gibt den Datensatz an, in den exportiert werden soll (nur bei `target: "field"` erforderlich).

</td></tr><tr><td>`fieldId`

</td><td>Definiert das genaue Feld im Datensatz, in das die exportierte Datei geschrieben wird.

</td></tr></tbody></table></figure>

#### 🔄 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: \"png\",
        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, Kreise, Polygone oder Text, 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.
- `polygon.fillColor`: Füllfarbe neuer Polygone, z. B. `rgba(0, 120, 255, 0.2)`. Ohne Angabe haben Polygone keine Füllung.
- `text.color`: Textfarbe für neuen Text (Standard `black`).
- `text.fontSize`: Schriftgröße neuer Texte in Canvas-Pixeln (Standard `16`).
- `text.fontWeight`: Schriftstärke, z. B. `bold` oder `600` (Standard `normal`).
- `text.fontFamily`: CSS-Schriftfamilie (Standard `Arial, Helvetica, sans-serif`).

💡 **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) |

#### Polygon- und Text-Werkzeug

Beide Werkzeuge sind nicht in der Standard-Toolbar. Mit `"polygon"` und `"text"` in `toolbarSettings` blendest du sie ein.

- `"polygon"`: Jede Ecke per Klick setzen. Beenden mit Klick auf die erste Ecke (ab drei Ecken), Doppelklick oder Enter; Esc bricht ab, Rücktaste entfernt die letzte Ecke.
- `"text"`: Dorthin klicken, wo der Text beginnen soll, tippen und mit Enter bestätigen (Umschalt+Enter = neue Zeile). Esc bricht ab. Doppelklick auf einen vorhandenen Text bearbeitet ihn.

**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. Unterstützte `type`-Werte: `rect`, `circle`, `polyline`, `polygon` (geschlossene Fläche mit `points` und optional `fill`), `text` (`x`, `y`, `text`, optional `fontSize`, `fontWeight`, `fontFamily`; `fill` ist die Textfarbe), `image` und `sticker`.
- `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:</p><ul><li data-preset-tag="p"><p>`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)

</li></ul>

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

<h5>🔍 `content`-Block im Detail:</h5>- `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.
<!-- /host -->


---

# 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

![](https://framerusercontent.com/images/dcMx5Gbm9HXvf5ETGtWzoMCLes.png)

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

![](https://framerusercontent.com/images/Mif9IVD9lV8C9GqZzriUa1cHjPA.png)

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


<!-- host:react -->
# Grid in React

Inhalte gleichzeitig in Zeilen und Spalten anordnen: Karten, KPI-Kacheln und Dashboards. Ohne Spaltenanzahl füllt das Grid die Zeile mit so vielen Spalten, wie die Breite zulässt, und passt sich so ohne Breakpoints an den Bildschirm an. Für eine Richtung (eine Zeile oder eine Spalte) und für Seiten-Rahmen nimmst du Arc Layout; das Grid nutzt du, wenn der Inhalt beide Dimensionen braucht.

Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.7`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).

## AI Defaults (read first)

- Ohne `columns` füllt das Grid die Zeile mit Spalten von mindestens `columnWidth` (Standard `200px`). Mit `columns` legst du eine feste Anzahl fest.
- `gap` ist der Abstand zwischen Zeilen und Spalten. Standard: `10px`.
- `columnSpan` und `rowSpan` an einem Block machen breite oder hohe Kacheln. Bei festem `columns` wird `columnSpan` auf diese Anzahl begrenzt.
- Das Grid ist standardmäßig `height: 'auto'` und so hoch wie sein Inhalt. Eine definierte `height` nur setzen, wenn es einen Rahmen ausfüllen soll.
- Das gemeinsame Aussehen aller Kacheln einmal in `blockDefaults` festlegen und Umrandungen mit `border` zeichnen, nicht mit `styles`.
- Widgets gehören in `blocks[].value`. Keine Wrapper-`div`-Elemente für das Grid selbst; die Spuren zeichnet das Grid.
- Nur Blöcke mit `clickable: true` reagieren auf Klicks. Sie rufen `onBlockClick` mit ihrem Index auf.

## Vollständiges Beispiel

<!-- react-example: grid-02-dashboard_spans.tsx -->
```tsx
import { useState } from 'react';
import {
  ArcWidgetBadge,
  ArcWidgetGrid,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

export default function Example() {
  const [selected, setSelected] = useState('none');
  const ids = ['revenue', 'orders', 'chart', 'inbox'];

  // `columnSpan` and `rowSpan` make a block wider or taller than one cell.
  // The chart block takes two columns and two rows; the neighbours flow around it.
  return (
    <ArcWidgetGrid
      onBlockClick={(index) => setSelected(ids[index] ?? 'none')}
      data={{
        columns: 4,
        gap: '12px',
        paddingX: '16px',
        paddingY: '16px',
        backgroundColor: '#F4F4F5',
        blockDefaults: {
          clickable: true,
          paddingX: '16px',
          paddingY: '16px',
          backgroundColor: '#FFFFFF',
          border: { color: '#D4D4D8', radius: '12px' },
        },
        blocks: [
          {
            blockId: 'revenue',
            value: <ArcWidgetText data={{ value: 'Revenue EUR 24,300', fontWeight: '700' }} />,
          },
          {
            blockId: 'orders',
            value: <ArcWidgetText data={{ value: 'Orders 128', fontWeight: '700' }} />,
          },
          {
            blockId: 'chart',
            columnSpan: 2,
            rowSpan: 2,
            alignX: 'center',
            alignY: 'center',
            value: 'Chart area (2 x 2)',
          },
          {
            blockId: 'inbox',
            columnSpan: 2,
            value: (
              <ArcWidgetBadge
                data={{
                  value: `Selected: ${selected}`,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## Features ausprobieren

### Responsive Spalten ohne Breakpoints

Nur Blöcke sind gesetzt. Ändere die Fensterbreite: Die Karten brechen in so viele Spalten um, wie passen.

<!-- react-example: grid-00-defaults.tsx -->
```tsx
import { ArcWidgetGrid } from '@arcrider/arcwidgets-react';

export default function Example() {
  // Only blocks are set. The Grid fits as many columns of at least 200px as the
  // width allows, so resize the window and the cards wrap by themselves.
  return (
    <ArcWidgetGrid
      data={{
        blocks: [
          { value: 'Card 1' },
          { value: 'Card 2' },
          { value: 'Card 3' },
          { value: 'Card 4' },
          { value: 'Card 5' },
          { value: 'Card 6' },
        ],
      }}
    />
  );
}
```

### Feste Spalten, Abstand und Kachel-Look

`columns` legt die Anzahl fest; die Spalten teilen sich die Breite. `blockDefaults` hält das gemeinsame Aussehen aller Kacheln, jeder Block setzt nur noch seinen Inhalt.

<!-- react-example: grid-01-fixed_columns.tsx -->
```tsx
import {
  ArcWidgetGrid,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

const tile = (title: string, amount: string) => ({
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'left',
        height: 'auto',
        gap: '4px',
        blocks: [
          {
            value: (
              <ArcWidgetText
                data={{ value: title, fontSize: '13px', fontColor: '#71717A' }}
              />
            ),
          },
          {
            value: (
              <ArcWidgetText
                data={{ value: amount, fontSize: '20px', fontWeight: '700' }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

export default function Example() {
  // `columns` fixes the column count; the columns share the width and shrink on narrow screens.
  // `blockDefaults` is the look every tile shares, so each block only sets its content.
  return (
    <ArcWidgetGrid
      data={{
        columns: 3,
        gap: '12px',
        paddingX: '16px',
        paddingY: '16px',
        backgroundColor: '#F4F4F5',
        blockDefaults: {
          alignY: 'top',
          paddingX: '16px',
          paddingY: '16px',
          backgroundColor: '#FFFFFF',
          border: { color: '#D4D4D8', radius: '12px' },
        },
        blocks: [
          tile('Open', '12'),
          tile('In review', '4'),
          tile('Done', '31'),
          tile('Revenue', 'EUR 24,300'),
          tile('Costs', 'EUR 9,800'),
          tile('Margin', '59.7%'),
        ],
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-id. Im Normalfall nicht nötig; wird automatisch erzeugt, wenn sie fehlt.

### data

Konfiguration vom Typ `ArcWidgetGridData`. Änderungen als neue Objekte übergeben; Geschäftsdaten und Auswahl im React-State halten.

### onAction

Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der spezifische Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).

### onBlockClick

Wird beim Klick auf einen `clickable` Block aufgerufen. `blockIndex` ist der nullbasierte Index in `data.blocks`.

```typescript
onBlockClick?: (blockIndex: number) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben.

### columns

Anzahl der Spalten, z. B. `3`. Weglassen (oder `'auto-fill'`) füllt die Zeile mit so vielen Spalten, wie die Breite zulässt. `'auto-fit'` richtet sich ebenfalls nach der Breite, streckt die Zellen aber, wenn es wenige Blöcke gibt. Standard: `'auto-fill'`.

Typ: `number | 'auto-fill' | 'auto-fit' | (string & {})`.

### columnWidth

Mindestbreite einer Spalte, z. B. `"280px"`. Die Spalten wachsen gleichmäßig, bis die Zeile gefüllt ist. Standard: `200px`. Bei festem `columns` ohne `columnWidth` teilen sich die Spalten die Breite und werden auf schmalen Bildschirmen beliebig schmal.

Typ: `string`.

### gap

Abstand zwischen den Blöcken, für Zeilen und Spalten gleich. Standard: `10px`.

Typ: `string`.

### width

Breite des Grids als CSS. Standard: `100%`.

Typ: `string`.

### height

Höhe des Grids als CSS. Eine definierte Höhe, wenn das Grid einen Rahmen ausfüllt, `'auto'` für inhaltsgroße Grids. Standard: `auto`.

Typ: `string`.

### paddingX

Innenabstand links und rechts.

Typ: `string`.

### paddingY

Innenabstand oben und unten.

Typ: `string`.

### backgroundColor

Hintergrundfarbe des Grids.

Typ: `string`.

### border

Linie und Eckenradius des Grid-Containers: `color`, `width`, `style`, `radius` und `sides`. Die Linie wird gezeichnet, sobald `color`, `width`, `style` oder `sides` gesetzt ist; `radius` allein rundet nur die Ecken. Blöcke nehmen dasselbe `border`-Objekt.

Typ: `ArcWidgetGridBorder`.

### blockDefaults

Werte, die jeder Block übernimmt, solange er keinen eigenen setzt, z. B. `{ paddingX: '16px', backgroundColor: '#FFFFFF', border: { radius: '12px' } }`. Ein am Block gesetzter Wert ersetzt den Standard vollständig, auch bei `border`. `value` und `blockId` kommen nie aus den Defaults.

Typ: `Omit<ArcWidgetGridBlock, 'value' | 'blockId'>`.

### styles

Rohe CSS-Deklarationen, die zuletzt auf den Grid-Container angewendet werden, z. B. `'padding: 8px; color: #333'`.

Typ: `string`.

### blocks

Zellen in Lesereihenfolge. Jeder Block hat eigene Größe, Spannweiten, Ausrichtung (`alignX`, `alignY`), Farben, `styles` und Inhalt in `value`; siehe `ArcWidgetGridBlock`.

Typ: `ArcWidgetGridBlock[]`.

## Verhalten und Grenzen

- Zeilen sind so hoch wie ihr höchster Block. `rowSpan` lässt einen Block mehrere Zeilen belegen, `columnSpan` mehrere Spalten. Nachfolgende Blöcke fließen um Blöcke mit Spannweite herum.

- Bei festem `columns` wird ein `columnSpan` über der Spaltenanzahl begrenzt, damit keine zusätzlichen Spalten entstehen. Im auto-fill-Modus gibt es keine feste Anzahl, dort gilt die Spannweite wie angegeben.

- Jeder Block ist ein horizontaler Flex-Container. Positioniere seinen Inhalt mit `blocks[].alignX` (`left`, `center`, `right`; Standard `left`) und `blocks[].alignY` (`top`, `center`, `bottom`, `stretch`; Standard `center`). `text-align` in `blocks[].styles` kann den Inhalt nicht zentrieren.

- `blocks[].width` und `blocks[].height` bestimmen die Größe des Inhalts innerhalb seiner Rasterfläche. `'fraction'` füllt die Fläche.

- `blocks[].value` unterstützt JSX. Events verschachtelter Komponenten direkt an deren Callback-Props binden.

- Grids lassen sich verschachteln. Jedes Grid wendet nur seine eigenen Einstellungen an, nie die des umgebenden Grids.

- Für Block-Klicks muss `clickable: true` am Block gesetzt sein. Das Grid selbst hat keinen Klick-Callback.

## Datentypen

Die folgenden Widget-Typen werden vom Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot` und `ArcReactWidgetProps` stehen ebenfalls zur Verfügung. Konfigurationsobjekte sind geschlossen, ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: grid -->
```typescript
export interface ArcWidgetGridBorder {
	color?: string;
	width?: string;
	style?: 'solid' | 'dashed' | 'dotted' | 'double';
	radius?: string;
	sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}

export interface ArcWidgetGridBlock {
	value?: ArcWidgetSlot;
	columnSpan?: number;
	rowSpan?: number;
	width?: string;
	height?: string;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom' | 'stretch';
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetGridBorder;
	color?: string;
	backgroundImage?: string;
	backgroundSize?: string;
	backgroundPosition?: string;
	lineHeight?: string;
	styles?: string;
	clickable?: boolean;
	blockId?: string;
}

export interface ArcWidgetGridData {
	columns?: number | 'auto-fill' | 'auto-fit' | (string & {});
	columnWidth?: string;
	gap?: string;
	width?: string;
	height?: string;
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetGridBorder;
	styles?: string;
	blockDefaults?: Omit<ArcWidgetGridBlock, 'value' | 'blockId'>;
	blocks?: ArcWidgetGridBlock[];
}

export interface ArcWidgetGridProps extends ArcReactWidgetProps<ArcWidgetGridData> {
	onBlockClick?: (blockIndex: 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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 `"10px"`, typically set to `"10px"` or `"16px"`.
- **height**: Use `"auto"` or `"100%"` depending on context.
- **blocks**: Each block can have `width`, `height`, `alignX`, `alignY`, `columnSpan`, `rowSpan`.
- **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):

![](https://framerusercontent.com/images/2YBdVENarVNdTsZmsI9uEVrHA.png)

<iframe src="https://www.youtube.com/embed/YqHm09bsqYg?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## 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: "",
        columnSpan: 1,
        rowSpan: 1,
        alignX: "center",
        alignY: "center",
        paddingY: "",
        paddingX: "",
        backgroundColor: "",
        lineHeight: "",
        styles: "",
        value: ""
       },{
        blockId: "",
        width: "",
        height: "",
        columnSpan: 1,
        rowSpan: 1,
        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: "",
        columnSpan: 1,
        rowSpan: 1,
        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: "", // default: 10px
```

### 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
```

### border

*border* zeichnet Linie und Ecken des Grids: `color`, `width`, `style`, `radius` und `sides`. Ohne `color`, `width`, `style` oder `sides` rundet `radius` nur die Ecken. Dasselbe Objekt funktioniert an jedem Block.


```javascript
border: { color: "#D4D4D8", radius: "12px" }, // Rahmen mit runden Ecken
border: { sides: ["bottom"] }, // nur Linie unten
```

### blockDefaults

*blockDefaults* sind Werte, die jeder Block übernimmt, solange er keinen eigenen setzt. Ein am Block gesetzter Wert ersetzt den Standard vollständig. `value`, `blockId` und `clickAction` kommen nie aus den Defaults.


```javascript
blockDefaults: { paddingX: "16px", backgroundColor: "#fff", border: { color: "#D4D4D8", radius: "12px" } },
```

## 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
```

### border

*border* zeichnet Linie und Ecken des Blocks, siehe die Einstellung gleichen Namens beim Grid.


```javascript
border: { color: "#D4D4D8", radius: "12px" },
```

### columnSpan

*columnSpan* gibt an, über wie viele Spalten sich der Block erstreckt. Bei festem *columns* wird der Wert auf die Spaltenanzahl begrenzt.


```javascript
columnSpan: 2, // Block belegt zwei Spalten
columnSpan: "", // default: 1
```

### rowSpan

*rowSpan* gibt an, über wie viele Zeilen sich der Block erstreckt. Die folgenden Blöcke fließen um ihn herum.


```javascript
rowSpan: 2, // Block belegt zwei Zeilen
rowSpan: "", // default: 1
```

### 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"
```
<!-- /host -->


---

# Custom Kanban

Source: https://www.arc-rider.com/docs/widgets/custom-kanban


<!-- host:react -->
# 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

Gesetzt sind nur Spaltentitel und Karten; alles andere ist Standard: dunkle Köpfe mit kleiner fetter Schrift, graue Spalten mit derselben Rundung wie der Button und ein kleiner Abstand zwischen Kopf und Spalte.

<!-- react-example: kanban-00-defaults.tsx -->
```tsx
import { ArcWidgetKanban, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

export default function Example() {
  // Only required fields are set on the board; everything else is the widget default.
  // The Layout gives the board a white surface.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  swimlanes: [
                    {
                      title: 'To do',
                      items: [
                        { id: 'brief', title: 'Write brief', subtitle: 'Due Friday' },
                        { id: 'venue', title: 'Book venue', subtitle: 'Due next week' },
                      ],
                    },
                    {
                      title: 'In progress',
                      items: [{ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' }],
                    },
                    {
                      title: 'Done',
                      items: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }],
                    },
                  ],
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## Features ausprobieren

Jedes Beispiel setzt nur die Werte, die die Variante ausmachen.

### Kopf ohne Farbe

`backgroundColorHeader: 'transparent'` lässt nur die Beschriftung über der grauen Spalte stehen. Setze eine dunkle `fontColor`; die Zähler-Bubble folgt der Schriftfarbe, und der Rahmen beim Ziehen bleibt dunkel.

<!-- react-example: kanban-01-plain_header.tsx -->
```tsx
import {
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanSwimlane,
} from '@arcrider/arcwidgets-react';

// A transparent header leaves only the label above the gray lane.
// Set `fontColor` to a dark color; the count bubble follows it.
const plainHeader: ArcWidgetKanbanSwimlane = {
  backgroundColorHeader: 'transparent',
  fontColor: '#18181B',
};

const lanes: ArcWidgetKanbanSwimlane[] = [
  {
    title: 'To do',
    items: [
      { id: 'brief', title: 'Write brief', subtitle: 'Due Friday' },
      { id: 'venue', title: 'Book venue', subtitle: 'Due next week' },
    ],
  },
  {
    title: 'In progress',
    items: [{ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' }],
  },
  {
    title: 'Done',
    items: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }],
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  swimlanes: lanes.map((lane) => ({
                    ...plainHeader,
                    ...lane,
                    amount: lane.items?.length,
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Kopffarben

Eine Kopffarbe pro Status. Die Kopffarbe umrandet auch die Spalte, wenn eine Karte darübergezogen wird; ein heller Kopf braucht eine dunkle `fontColor`.

<!-- react-example: kanban-02-header_colors.tsx -->
```tsx
import {
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanSwimlane,
} from '@arcrider/arcwidgets-react';

// One header color per status. The header color also outlines the lane while a card is dragged over it.
// A light header needs a dark `fontColor`.
const lanes: ArcWidgetKanbanSwimlane[] = [
  {
    title: 'Backlog',
    backgroundColorHeader: '#E4E4E7',
    fontColor: '#18181B',
    items: [{ id: 'survey', title: 'Customer survey', subtitle: 'Not planned yet' }],
  },
  {
    title: 'In progress',
    backgroundColorHeader: '#2563EB',
    items: [
      { id: 'poster', title: 'Design poster', subtitle: 'Draft 2' },
      { id: 'venue', title: 'Book venue', subtitle: 'Waiting for offer' },
    ],
  },
  {
    title: 'Review',
    backgroundColorHeader: '#D97706',
    items: [{ id: 'brief', title: 'Write brief', subtitle: 'With Anna' }],
  },
  {
    title: 'Done',
    backgroundColorHeader: '#16A34A',
    backgroundColorBody: '#F0FDF4',
    items: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }],
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  swimlanes: lanes.map((lane) => ({ ...lane, amount: lane.items?.length })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Slots im Kopf

`slotLeft` steht vor dem Titel, `slotRight` hinter der Zähler-Bubble. Beide nehmen beliebige Inhalte, z. B. einen Status-Punkt oder einen Icon-Button; Klicks in einem Slot bleiben bei dessen Inhalt.

<!-- react-example: kanban-03-header_slots.tsx -->
```tsx
import { useState } from 'react';
import {
  ArcWidgetButton,
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanItem,
} from '@arcrider/arcwidgets-react';
import { CircleIcon, PlusIcon } from '@phosphor-icons/react';

const lanes = [
  { id: 'todo', title: 'To do', color: '#A1A1AA' },
  { id: 'doing', title: 'In progress', color: '#3B82F6' },
  { id: 'done', title: 'Done', color: '#22C55E' },
];

const initialCards: Record<string, ArcWidgetKanbanItem[]> = {
  todo: [{ id: 'brief', title: 'Write brief', subtitle: 'Due Friday' }],
  doing: [{ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' }],
  done: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }],
};

export default function Example() {
  const [cards, setCards] = useState(initialCards);

  const addCard = (laneId: string) =>
    setCards((current) => {
      const count = current[laneId].length + 1;
      return {
        ...current,
        [laneId]: [...current[laneId], { id: `${laneId}-${count}`, title: `New card ${count}` }],
      };
    });

  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  swimlanes: lanes.map((lane) => ({
                    title: lane.title,
                    amount: cards[lane.id].length,
                    // `slotLeft` sits before the title, `slotRight` after the count bubble.
                    slotLeft: <CircleIcon size={10} weight="fill" color={lane.color} />,
                    // The default button matches the dark header and lightens on hover.
                    slotRight: (
                      <ArcWidgetButton
                        data={{ title: '', icon: <PlusIcon size={14} />, paddingX: '0.4em', paddingY: '0.4em' }}
                        onClick={() => addCard(lane.id)}
                      />
                    ),
                    items: cards[lane.id],
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Karten

`title`, `subtitle` und `value` nehmen Text oder ein beliebiges Widget, hier ein Badge für die Priorität. `borderPosition: 'left'` macht aus dem Kartenrand einen Akzentstreifen.

<!-- react-example: kanban-04-cards.tsx -->
```tsx
import {
  ArcWidgetBadge,
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanItem,
} from '@arcrider/arcwidgets-react';

const priorities: Record<string, { label: string; color: string; stroke: 'solid' | 'dashed' | 'dotted' }> = {
  high: { label: 'High', color: '#DC2626', stroke: 'solid' },
  normal: { label: 'Normal', color: '#2563EB', stroke: 'solid' },
  low: { label: 'Low', color: '#64748B', stroke: 'dashed' },
};

type Task = { id: string; title: string; owner: string; due: string; priority: keyof typeof priorities };

const tasks: Record<string, Task[]> = {
  'To do': [
    { id: 'T-12', title: 'Replace workshop lights', owner: 'Facilities', due: 'Mon', priority: 'high' },
    { id: 'T-14', title: 'Order office supplies', owner: 'Office', due: 'Fri', priority: 'low' },
  ],
  'In progress': [
    { id: 'T-09', title: 'Renew design software', owner: 'Design', due: 'Wed', priority: 'normal' },
  ],
  Done: [{ id: 'T-03', title: 'Service ventilation', owner: 'Operations', due: 'Done', priority: 'normal' }],
};

// `title`, `subtitle` and `value` take text or any widget; `borderPosition: 'left'` turns the border into an accent stripe.
// `borderStroke` makes the stripe solid (default), dashed or dotted.
const toCard = (task: Task): ArcWidgetKanbanItem => {
  const priority = priorities[task.priority];
  return {
    id: task.id,
    title: task.title,
    subtitle: `${task.id} · ${task.owner} · ${task.due}`,
    value: <ArcWidgetBadge data={{ value: priority.label, singleColor: priority.color }} />,
    borderColor: priority.color,
    borderWidth: '3px',
    borderPosition: 'left',
    borderStroke: priority.stroke,
    borderRadius: '8px',
  };
};

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '340px',
                  swimlanes: Object.entries(tasks).map(([title, list]) => ({
                    title,
                    amount: list.length,
                    items: list.map(toCard),
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Gruppen

`sections` gruppieren die Karten einer Spalte. Gib jeder Gruppe eine stabile `id`, damit ihr Auf- oder Zuklappzustand gemerkt wird.

<!-- react-example: kanban-05-sections.tsx -->
```tsx
import { ArcWidgetKanban, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

const lanes = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress' },
];
const groups = [
  { id: 'urgent', title: 'Urgent' },
  { id: 'routine', title: 'Routine' },
];
const tasks = [
  { id: 'T-12', title: 'Replace workshop lights', lane: 'todo', group: 'urgent' },
  { id: 'T-14', title: 'Order office supplies', lane: 'todo', group: 'routine' },
  { id: 'T-15', title: 'Replace reception chair', lane: 'todo', group: 'routine' },
  { id: 'T-09', title: 'Inspect ventilation fault', lane: 'doing', group: 'urgent' },
  { id: 'T-10', title: 'Renew design software', lane: 'doing', group: 'routine' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '400px',
                  swimlanes: lanes.map((lane) => {
                    const laneTasks = tasks.filter((task) => task.lane === lane.id);
                    return {
                      title: lane.title,
                      amount: laneTasks.length,
                      // `sections` replace `items`. A stable `id` keeps each group's open or collapsed state.
                      sections: groups.map((group) => ({
                        id: `${lane.id}-${group.id}`,
                        title: group.title,
                        items: laneTasks
                          .filter((task) => task.group === group.id)
                          .map((task) => ({ id: task.id, title: task.title, subtitle: task.id })),
                      })),
                    };
                  }),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Leere Spalten und Einklappen

`empty` zeigt einen Platzhalter in Spalten ohne Karten; ein eigenes `empty` an der Spalte hat Vorrang. `collapsible: true` fügt jedem Kopf einen Umschalter hinzu.

<!-- react-example: kanban-06-empty_collapsible.tsx -->
```tsx
import { ArcWidgetKanban, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  // `collapsible` adds a toggle to every header; the state is remembered per widget `id`.
                  collapsible: true,
                  // The built-in placeholder text is German, so set `value` for other languages.
                  empty: { value: 'No cards yet' },
                  swimlanes: [
                    {
                      title: 'To do',
                      amount: 2,
                      items: [
                        { id: 'brief', title: 'Write brief', subtitle: 'Due Friday' },
                        { id: 'venue', title: 'Book venue', subtitle: 'Due next week' },
                      ],
                    },
                    { title: 'In progress', amount: 0, items: [] },
                    // A lane's own `empty` overrides the board setting.
                    { title: 'Blocked', amount: 0, items: [], empty: { value: 'Nothing blocked' } },
                  ],
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Einklapp-Icons

Mit `iconExpand` und `iconCollapse` setzt du eigene Icons für den Umschalter; ohne sie ist er ein Chevron, das sich dreht. Jeder Inhalt geht, z. B. ein Icon oder ein Button.

<!-- react-example: kanban-10-collapse_icons.tsx -->
```tsx
import { ArcWidgetKanban, ArcWidgetLayout } from '@arcrider/arcwidgets-react';
import { MinusIcon, PlusIcon } from '@phosphor-icons/react';

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '320px',
                  // `collapsible: true` alone shows a chevron that turns while collapsed.
                  // `iconExpand` shows while a lane is collapsed (a click opens it),
                  // `iconCollapse` while it is open (a click closes it).
                  // Add `defaultCollapsed: true` to start with every lane closed.
                  collapsible: {
                    iconExpand: <PlusIcon size={14} />,
                    iconCollapse: <MinusIcon size={14} />,
                  },
                  swimlanes: [
                    {
                      title: 'To do',
                      amount: 2,
                      items: [
                        { id: 'brief', title: 'Write brief', subtitle: 'Due Friday' },
                        { id: 'venue', title: 'Book venue', subtitle: 'Due next week' },
                      ],
                    },
                    {
                      title: 'In progress',
                      amount: 1,
                      items: [{ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' }],
                    },
                    {
                      title: 'Done',
                      amount: 1,
                      items: [{ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' }],
                    },
                  ],
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Akzentlinien

`insetBorder` zeichnet eine Linie mit runden Enden innerhalb der Karte. Teile sie in `segments`, um zu zeigen, wer oder was beteiligt ist, zum Beispiel eine Farbe pro Person. Jedes Segment hat eine eigene `color` und ein `label`, das als Tooltip erscheint. `size` legt die Länge entlang der Linie fest: `'fraction'` (oder `'auto'`) teilt den Rest gleichmäßig, `'24px'` oder `'25%'` sind fest. Feste Segmente, die die Linie nicht füllen, sitzen am Anfang; mit `align` verschiebst du sie. Jede Karte zeigt standardmäßig eine schwarze Linie am linken Rand. Mit `insetBorder: false` blendest du sie aus; setzt du `insetBorder` am Board (`data`), gestaltest du die Linie aller Karten um, zum Beispiel `{ color: '#A1A1AA' }` auf einem dunklen Board; Felder der Karte selbst haben Vorrang. `position` setzt die Linie nach `right`, `top` oder `bottom`.

<!-- react-example: kanban-11-inset_lines.tsx -->
```tsx
import {
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanInsetBorder,
  type ArcWidgetKanbanItem,
} from '@arcrider/arcwidgets-react';

const people = {
  anna: { name: 'Anna', color: '#DC2626' },
  ben: { name: 'Ben', color: '#2563EB' },
  clara: { name: 'Clara', color: '#16A34A' },
};

type Person = keyof typeof people;
type Owner = { person: Person; size?: string };
type Task = { id: string; title: string; owners: Owner[]; note?: string; side?: ArcWidgetKanbanInsetBorder['position'] };

const tasks: Record<string, Task[]> = {
  'To do': [
    { id: 'T-12', title: 'Replace workshop lights', owners: [{ person: 'anna' }] },
    { id: 'T-14', title: 'Order office supplies', owners: [{ person: 'anna' }, { person: 'ben' }, { person: 'clara' }] },
  ],
  'In progress': [
    { id: 'T-09', title: 'Renew design software', owners: [{ person: 'ben', size: '66%' }, { person: 'clara' }], note: 'Ben has the larger share' },
  ],
  Done: [{ id: 'T-03', title: 'Service ventilation', owners: [{ person: 'clara' }], note: 'Line at the bottom', side: 'bottom' }],
};

// `insetBorder` draws a line with round ends inside the card. Cut it into `segments` to show who is
// involved: each segment has its own `color` and a `label` that appears as a tooltip.
// `size` sets the length along the line: 'fraction' (or 'auto') shares what is left equally,
// '24px' or '25%' are fixed. Every card has a black line on the left by default; without `segments` it stays one piece.
// `position` moves the line to 'right', 'top' or 'bottom'.
const toCard = (task: Task): ArcWidgetKanbanItem => ({
  id: task.id,
  title: task.title,
  subtitle: task.note ?? task.id,
  insetBorder: {
    position: task.side,
    segments: task.owners.map(({ person, size }) => ({
      color: people[person].color,
      label: people[person].name,
      size,
    })),
  },
});

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '340px',
                  swimlanes: Object.entries(tasks).map(([title, list]) => ({
                    title,
                    amount: list.length,
                    items: list.map(toCard),
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Reichhaltige Karten im breiten Board

Ein Layout im `value` der Karte setzt sie frei zusammen: oben ein Badge und ein Icon, darunter Text, unten Team-Porträts und Icon-Buttons. Ein Block mit `width: 'fraction'` nimmt die freie Breite und schiebt die folgenden Blöcke an den rechten Rand. Das Board hat `styles.minWidth`: Spalten teilen sich die Breite gleichmäßig, und sobald sie schmaler als dieser Wert würden, scrollt das Board seitlich (`scrollSettings.scrollX` einschalten). Eine Spalte selbst scrollt nie seitlich. Beide Scrollbars sind standardmäßig ausgeblendet; `scrollBar` zeigt und gestaltet sie wie bei der Tabelle. Die horizontale Leiste sitzt mit etwas Abstand unter den Spalten, der Track hat keine Farbe, solange du keine setzt.

<!-- react-example: kanban-12-card_layout.tsx -->
```tsx
import type { ReactNode } from 'react';
import {
  ArcWidgetBadge,
  ArcWidgetButton,
  ArcWidgetImage,
  ArcWidgetKanban,
  ArcWidgetLayout,
  ArcWidgetText,
  type ArcWidgetKanbanItem,
} from '@arcrider/arcwidgets-react';
import { ChatCircleIcon, FlagIcon, PaperclipIcon } from '@phosphor-icons/react';

// Generated square portraits keep the example offline.
const portrait = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    "<svg xmlns='http://www.w3.org/2000/svg' width='96' height='96'>" +
      `<rect width='96' height='96' fill='${color}'/>` +
      "<circle cx='48' cy='39' r='18' fill='#FFFFFF' fill-opacity='0.9'/>" +
      "<path d='M15 96 C15 71 81 71 81 96 Z' fill='#FFFFFF' fill-opacity='0.9'/>" +
      '</svg>',
  )}`;

const people: Record<string, { name: string; color: string }> = {
  am: { name: 'Alex Morgan', color: '#6366F1' },
  sl: { name: 'Sam Lee', color: '#0EA5E9' },
  rd: { name: 'Robin Diaz', color: '#F59E0B' },
  kn: { name: 'Kim Novak', color: '#10B981' },
};

const priorities = {
  high: { label: 'High', color: '#DC2626' },
  normal: { label: 'Normal', color: '#2563EB' },
  low: { label: 'Low', color: '#64748B' },
};

type Task = { id: string; title: string; note: string; priority: keyof typeof priorities; team: string[] };

const board: Record<string, Task[]> = {
  Backlog: [
    { id: 'T-21', title: 'Plan the autumn campaign', note: 'Channels, budget and the calendar.', priority: 'low', team: ['am'] },
    { id: 'T-22', title: 'Collect customer quotes', note: 'Three short quotes for the landing page.', priority: 'normal', team: ['sl', 'rd'] },
  ],
  Design: [
    { id: 'T-17', title: 'Poster series', note: 'Three formats, print and screen.', priority: 'high', team: ['am', 'sl', 'kn'] },
  ],
  Build: [
    { id: 'T-12', title: 'Newsletter template', note: 'Header, two columns and a footer with legal links.', priority: 'normal', team: ['rd', 'kn'] },
    { id: 'T-14', title: 'Booking form', note: 'Validation and a confirmation mail.', priority: 'high', team: ['sl'] },
  ],
  Review: [{ id: 'T-09', title: 'Price list 2027', note: 'Waiting for sign-off.', priority: 'normal', team: ['am', 'kn'] }],
  Testing: [{ id: 'T-06', title: 'Checkout on mobile', note: 'iOS and Android, three browsers.', priority: 'high', team: ['rd'] }],
  Done: [{ id: 'T-03', title: 'Kickoff call', note: 'Notes shared with everyone.', priority: 'low', team: ['am', 'sl', 'rd', 'kn'] }],
};

const iconButton = (icon: ReactNode, onClick: () => void) => (
  <ArcWidgetButton
    data={{
      title: '',
      icon,
      paddingX: '0.4em',
      paddingY: '0.4em',
      backgroundColor: '#F4F4F5',
      fontColor: '#52525B',
      hoverActions: { backgroundColor: '#E4E4E7', fontColor: '#18181B' },
    }}
    onClick={onClick}
  />
);

// The whole card is one Layout in `value`: three rows, each a horizontal Layout.
// A block with `width: 'fraction'` takes the free width and pushes the blocks after it to the right edge.
const toCard = (task: Task): ArcWidgetKanbanItem => {
  const priority = priorities[task.priority];
  return {
    id: task.id,
    value: (
      <ArcWidgetLayout
        data={{
          direction: 'vertical',
          alignX: 'stretch',
          height: 'auto',
          gap: '10px',
          blocks: [
            {
              value: (
                <ArcWidgetLayout
                  data={{
                    direction: 'horizontal',
                    alignX: 'left',
                    alignY: 'center',
                    height: 'auto',
                    gap: '8px',
                    blocks: [
                      { width: 'auto', value: <FlagIcon size={16} weight="fill" color={priority.color} /> },
                      {
                        width: 'fraction',
                        value: (
                          <ArcWidgetText
                            data={{ value: task.title, fontSize: '13px', fontWeight: 600, fontColor: '#333333' }}
                          />
                        ),
                      },
                      {
                        width: 'auto',
                        value: <ArcWidgetBadge data={{ value: priority.label, singleColor: priority.color }} />,
                      },
                    ],
                  }}
                />
              ),
            },
            {
              value: (
                <ArcWidgetText
                  data={{ value: `${task.id} · ${task.note}`, fontSize: '12px', fontColor: '#666666' }}
                />
              ),
            },
            {
              value: (
                <ArcWidgetLayout
                  data={{
                    direction: 'horizontal',
                    alignX: 'left',
                    alignY: 'center',
                    height: 'auto',
                    gap: '4px',
                    blocks: [
                      // The faces form their own Layout: a negative gap overlaps them, the first one lies on top.
                      {
                        width: 'auto',
                        value: (
                          <ArcWidgetLayout
                            data={{
                              direction: 'horizontal',
                              alignX: 'left',
                              alignY: 'center',
                              width: 'auto',
                              height: 'auto',
                              gap: '-8px',
                              overlapOrder: 'start',
                              blocks: task.team.map((id) => ({
                                width: 'auto',
                                // `title` names the person on hover.
                                value: (
                                  <ArcWidgetImage
                                    data={{
                                      value: portrait(people[id].color),
                                      alt: people[id].name,
                                      title: people[id].name,
                                      width: '24px',
                                      height: '24px',
                                      objectFit: 'cover',
                                      loading: 'eager',
                                      border: { color: '#FFFFFF', width: '2px', radius: '50%' },
                                    }}
                                  />
                                ),
                              })),
                            }}
                          />
                        ),
                      },
                      { width: 'fraction', value: '' },
                      { width: 'auto', value: iconButton(<ChatCircleIcon size={14} />, () => undefined) },
                      { width: 'auto', value: iconButton(<PaperclipIcon size={14} />, () => undefined) },
                    ],
                  }}
                />
              ),
            },
          ],
        }}
      />
    ),
  };
};

export default function Example() {
  // Six lanes of at least 300px: when the board is wider they share the width equally,
  // when it is narrower the board scrolls sideways. A lane never gets a scrollbar of its own sideways.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '380px',
                  insetBorder: false,
                  styles: { minWidth: '300px' },
                  scrollSettings: { scrollX: { scrollbar: { enabled: true } } },
                  // Both scrollbar kinds are hidden by default. Here the board bar below the lanes is shown.
                  scrollBar: { board: { showScrollBar: true } },
                  swimlanes: Object.entries(board).map(([title, list]) => ({
                    title,
                    amount: list.length,
                    items: list.map(toCard),
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Drag & Drop mit Speichern

Gib das Speicher-Promise aus `onItemDrop` zurück. Solange es läuft, bleibt das Board gesperrt; wird es abgelehnt, springt die Karte an ihre alte Position zurück. Mit dem Button lässt du das nächste Speichern scheitern.

<!-- react-example: kanban-07-drag_drop.tsx -->
```tsx
import { useRef, useState } from 'react';
import {
  ArcWidgetButton,
  ArcWidgetKanban,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

const lanes = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress' },
  { id: 'done', title: 'Done' },
];

const initialTasks = [
  { id: 'T-12', title: 'Write brief', lane: 'todo' },
  { id: 'T-14', title: 'Book venue', lane: 'todo' },
  { id: 'T-09', title: 'Design poster', lane: 'doing' },
  { id: 'T-03', title: 'Kickoff call', lane: 'done' },
];

// Stands in for a server request.
const save = (fail: boolean) =>
  new Promise<void>((resolve, reject) => {
    window.setTimeout(() => (fail ? reject(new Error('Save failed')) : resolve()), 800);
  });

export default function Example() {
  const [tasks, setTasks] = useState(initialTasks);
  const [failNext, setFailNext] = useState(false);
  const [status, setStatus] = useState('Drag a card to another lane.');

  const columns = lanes.map((lane) => ({ ...lane, tasks: tasks.filter((task) => task.lane === lane.id) }));

  // The Layout keeps the first Kanban element it was given, so `onItemDrop` below would read
  // the values of the first render. The ref always holds the current ones.
  const latest = useRef({ columns, failNext });
  latest.current = { columns, failNext };

  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        gap: '12px',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetLayout
                data={{
                  direction: 'horizontal',
                  alignY: 'center',
                  height: 'auto',
                  gap: '12px',
                  blocks: [
                    {
                      width: 'auto',
                      value: (
                        <ArcWidgetButton
                          data={{ title: failNext ? 'Next save fails' : 'Next save succeeds', width: '170px' }}
                          onClick={() => setFailNext((current) => !current)}
                        />
                      ),
                    },
                    { value: <ArcWidgetText data={{ value: status, fontColor: '#52525B' }} /> },
                  ],
                }}
              />
            ),
          },
          {
            value: (
              <ArcWidgetKanban
                data={{
                  height: '300px',
                  swimlanes: columns.map((column) => ({
                    title: column.title,
                    amount: column.tasks.length,
                    items: column.tasks.map((task) => ({ id: task.id, title: task.title, subtitle: task.id })),
                  })),
                }}
                // The board shows the move at once and stays locked while the promise runs.
                // Resolve: keep the move in state. Reject: the card goes back to its old position.
                onItemDrop={(payload) => {
                  const { columns, failNext } = latest.current;
                  const task = columns[payload.source_swimlane_index]?.tasks[payload.item_index];
                  const target = lanes[payload.target_swimlane_index];
                  if (!task || !target) return;
                  setStatus(`Saving ${task.id} …`);
                  return save(failNext).then(
                    () => {
                      setTasks((current) => [
                        ...current.filter((item) => item.id !== task.id),
                        { ...task, lane: target.id },
                      ]);
                      setStatus(`${task.id} saved in ${target.title}.`);
                    },
                    (error) => {
                      setStatus(`${task.id} not saved, moved back.`);
                      throw error;
                    },
                  );
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Klick und Details

`onItemClick` liefert die Position der Karte; ordne sie deinem eigenen Datensatz zu und zeige die Details neben dem Board.

<!-- react-example: kanban-08-click_details.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetKanban, ArcWidgetLayout, ArcWidgetText } from '@arcrider/arcwidgets-react';

const lanes = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress' },
];

const tasks = [
  { id: 'T-12', title: 'Replace workshop lights', lane: 'todo', owner: 'Facilities', note: 'Check the fitting before ordering.' },
  { id: 'T-14', title: 'Renew design software', lane: 'todo', owner: 'Design', note: 'Count the seats before renewing.' },
  { id: 'T-09', title: 'Inspect ventilation', lane: 'doing', owner: 'Operations', note: 'Inspection booked for Thursday.' },
];

export default function Example() {
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const columns = lanes.map((lane) => ({ ...lane, tasks: tasks.filter((task) => task.lane === lane.id) }));
  const selected = tasks.find((task) => task.id === selectedId);

  const details = selected ? (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        height: 'auto',
        gap: '6px',
        blocks: [
          { value: <ArcWidgetText data={{ value: selected.title, fontWeight: '700' }} /> },
          { value: <ArcWidgetText data={{ value: `${selected.id} · ${selected.owner}`, fontColor: '#52525B' }} /> },
          { value: <ArcWidgetText data={{ value: selected.note }} /> },
        ],
      }}
    />
  ) : (
    <ArcWidgetText data={{ value: 'Click a card to see its details.', fontColor: '#71717A' }} />
  );

  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignY: 'stretch',
        height: 'auto',
        gap: '12px',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#FFFFFF',
        border: { radius: '12px' },
        blocks: [
          {
            width: 'fraction',
            value: (
              <ArcWidgetKanban
                data={{
                  height: '300px',
                  swimlanes: columns.map((column) => ({
                    title: column.title,
                    amount: column.tasks.length,
                    items: column.tasks.map((task) => ({
                      id: task.id,
                      title: task.title,
                      subtitle: task.owner,
                      draggable: false,
                    })),
                  })),
                }}
                // Indices point into the data you passed; map them back to your own records.
                onItemClick={(_, payload) => {
                  const task = columns[payload.swimlane_index]?.tasks[payload.item_index];
                  setSelectedId(task?.id ?? null);
                }}
              />
            ),
          },
          {
            width: '240px',
            alignY: 'top',
            paddingX: '16px',
            paddingY: '16px',
            backgroundColor: '#F4F4F5',
            border: { radius: '8px' },
            value: details,
          },
        ],
      }}
    />
  );
}
```

### Darkmode

Auf dunklem Grund setzt du die Farben von Kopf, Spaltenkörper und Karten selbst: `backgroundColorHeader`, `backgroundColorBody` und `fontColor` je Spalte, `backgroundColor`, `borderColor` und `fontColor` je Karte. Die Zähler-Bubble folgt der Schriftfarbe des Kopfs.

<!-- react-example: kanban-09-dark_mode.tsx -->
```tsx
import {
  ArcWidgetKanban,
  ArcWidgetLayout,
  type ArcWidgetKanbanItem,
  type ArcWidgetKanbanSwimlane,
} from '@arcrider/arcwidgets-react';

// Dark surface: set the colors of header, lane body and cards.
// The count bubble follows the header text color; the drag outline uses the header color.
const darkLane: ArcWidgetKanbanSwimlane = {
  backgroundColorHeader: '#27272A',
  backgroundColorBody: '#18181B',
  fontColor: '#FAFAFA',
};

// `fontColor` colors the plain text of a card; the card itself needs its own background and border.
// The board's `insetBorder` sets the accent line of every card: black by default, so it is made light here.
const card = (item: ArcWidgetKanbanItem): ArcWidgetKanbanItem => ({
  backgroundColor: '#27272A',
  borderColor: '#3F3F46',
  borderRadius: '8px',
  fontColor: '#FAFAFA',
  ...item,
});

const lanes: ArcWidgetKanbanSwimlane[] = [
  {
    title: 'To do',
    items: [
      card({ id: 'brief', title: 'Write brief', subtitle: 'Due Friday' }),
      card({ id: 'venue', title: 'Book venue', subtitle: 'Due next week' }),
    ],
  },
  {
    title: 'In progress',
    items: [card({ id: 'poster', title: 'Design poster', subtitle: 'Draft 2' })],
  },
  {
    title: 'Done',
    items: [card({ id: 'kickoff', title: 'Kickoff call', subtitle: 'Completed' })],
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        height: 'auto',
        paddingX: '12px',
        paddingY: '12px',
        backgroundColor: '#09090B',
        // On a dark surface a fine line separates the board from its surroundings.
        border: { color: '#27272A', radius: '12px' },
        blocks: [
          {
            value: (
              <ArcWidgetKanban
                data={{
                  insetBorder: { color: '#A1A1AA' },
                  height: '320px',
                  swimlanes: lanes.map((lane) => ({
                    ...darkLane,
                    ...lane,
                    amount: lane.items?.length,
                  })),
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Maus-Event und Position der Karte. Wird nicht für Karten mit `clickable: false` und nicht direkt nach einem Ziehen ausgelöst.

```typescript
onItemClick?: (event: MouseEvent, payload: ArcWidgetKanbanItemClickPayload) => void;
```

### onItemDrop

Herkunft und neue Position einer verschobenen Karte; die Karte landet am Ende der Zielspalte bzw. -gruppe. Ein zurückgegebenes Speicher-Promise sperrt das Board bis zum Abschluss; bei Ablehnung springt die Karte an ihre alte Position zurück.

```typescript
onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise<unknown>;
```

## 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"`. Standard ist `100%`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### empty

Anzeige für leere Spalten; `true` oder eine eigene Beschriftung und Farben. Standardmäßig aus; ein eigenes `empty` an der Spalte hat Vorrang. Der eingebaute Text ist deutsch; setze für andere Sprachen `value`.

Typ: `boolean | ArcWidgetKanbanEmpty`.

### swimlanes

Spalten mit flachen `items` oder benannten `sections`, dazu Kopffarben, Zähler-Bubble, Slots im Kopf (`slotLeft`, `slotRight`) und Mindestbreite. `backgroundColorHeader: 'transparent'` ergibt einen Kopf ohne Farbe.

Typ: `ArcWidgetKanbanSwimlane[]`.

### scrollSettings

Scrollen des gesamten Boards: `scrollX` und `scrollY`, jeweils mit `scrollbar: { enabled: boolean }`. Beide sind standardmäßig aus. Eine Spalte scrollt ihre Karten selbst vertikal; das schaltest du mit `scrollSettings.scrollY` an der Spalte ab.

Typ: `ArcWidgetKanbanScrollSettings`.

### styles

Maße des Boards.

- `minWidth`: kleinste Breite aller Spalten, z. B. `'300px'`. Die Spalten teilen sich die freie Breite gleichmäßig; passen sie nicht mehr, scrollt das Board seitlich (braucht `scrollSettings.scrollX`). `minWidth` an einer Spalte hat Vorrang. Standard: `150px`.

Typ: `{ minWidth?: string }`.

### scrollBar

Zeigt und gestaltet die Scrollbars: die vertikale Leiste in jeder Spalte und die horizontale Leiste des Boards unter den Spalten. Beide sind standardmäßig ausgeblendet, gescrollt wird trotzdem. Die Felder entsprechen dem `scrollBar` der Tabelle (`showScrollBar`, `height`, `backgroundColor`, `handle`), der Track hat aber standardmäßig keine Farbe. `board` und `lanes` ändern nur eine der beiden Leisten.

Typ: `ArcWidgetKanbanScrollBar`.

### collapsible

Fügt jedem Spaltenkopf einen Umschalter zum Einklappen der Spalte hinzu. `true` zeigt das eingebaute Chevron, das sich beim Einklappen dreht. Ein Objekt setzt zusätzlich `defaultCollapsed` (eingeklappt starten) und eigene Icons: `iconExpand` (solange eingeklappt, ein Klick klappt auf) und `iconCollapse` (solange offen, ein Klick klappt zu). Die Icons gelten auch für die Umschalter der Gruppen. Der Zustand wird gemerkt; die Wahl des Nutzers schlägt `defaultCollapsed`.

Typ: `boolean | ArcWidgetKanbanCollapsible`.

## Verhalten und Grenzen

- Eine Spalte enthält entweder flache `items` oder benannte `sections` mit eigenen `items`. Gib Gruppen eine stabile `id`, damit ihr Auf- oder Zuklappzustand gemerkt wird.

- `onItemClick` liefert zuerst das Maus-Event, dann Indizes für Spalte, Gruppe und Karte. Diese Indizes beziehen sich auf die übergebene Datenstruktur; per `hideWhenEmpty` ausgeblendete Gruppen werden beim Zählen übersprungen.

- Karten sind standardmäßig ziehbar; mit `draggable: false` sperrst du eine Karte. Gib dein Speicher-Promise aus `onItemDrop` zurück; bei einem abgelehnten Promise springt die Karte an ihre alte Position zurück. 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: kanban -->
```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;
	backgroundColor?: string;
	backgroundColorTop?: string;
	backgroundColorBottom?: string;
	fontColor?: string;
	paddingX?: string;
	paddingY?: string;
	borderRadius?: string;
	borderColor?: string;
	borderWidth?: string;
	borderPosition?: 'left' | 'right' | 'top' | 'bottom';
	borderStroke?: 'solid' | 'dashed' | 'dotted';
	insetBorder?: boolean | ArcWidgetKanbanInsetBorder;
}

export interface ArcWidgetKanbanInsetSegment {
	color?: string;
	stroke?: 'solid' | 'dashed' | 'dotted';
	label?: string;
	size?: 'fraction' | 'auto' | (string & {});
}

export interface ArcWidgetKanbanInsetBorder {
	enabled?: boolean;
	position?: 'left' | 'right' | 'top' | 'bottom';
	width?: string;
	stroke?: 'solid' | 'dashed' | 'dotted';
	color?: string;
	align?: 'start' | 'center' | 'end';
	segments?: ArcWidgetKanbanInsetSegment[];
}

export interface ArcWidgetKanbanSection {
	id?: string | number;
	title?: ArcWidgetSlot;
	items?: ArcWidgetKanbanItem[];
	hideWhenEmpty?: boolean;
	collapsed?: boolean;
}

export interface ArcWidgetKanbanEmpty {
	enabled?: boolean;
	value?: ArcWidgetSlot;
	backgroundColor?: string;
	fontColor?: string;
	fontWeight?: string | number;
}

export interface ArcWidgetKanbanScrollAxis {
	scrollbar?: {
		enabled?: boolean;
	};
}

export interface ArcWidgetKanbanScrollBarHandle {
	backgroundColor?: string;
	borderRadius?: string;
}

export interface ArcWidgetKanbanScrollBarLook {
	showScrollBar?: boolean;
	height?: string;
	backgroundColor?: string;
	handle?: ArcWidgetKanbanScrollBarHandle;
}

export interface ArcWidgetKanbanScrollBar extends ArcWidgetKanbanScrollBarLook {
	board?: ArcWidgetKanbanScrollBarLook;
	lanes?: ArcWidgetKanbanScrollBarLook;
}

export interface ArcWidgetKanbanScrollSettings {
	scrollX?: ArcWidgetKanbanScrollAxis;
	scrollY?: ArcWidgetKanbanScrollAxis;
}

export interface ArcWidgetKanbanSwimlaneScrollSettings {
	scrollY?: ArcWidgetKanbanScrollAxis;
}

export interface ArcWidgetKanbanSwimlane {
	title?: ArcWidgetSlot;
	amount?: ArcWidgetSlot;
	showAmount?: boolean;
	slotLeft?: ArcWidgetSlot;
	slotRight?: ArcWidgetSlot;
	minWidth?: string;
	backgroundColorHeader?: string;
	backgroundColorBody?: string;
	fontColor?: string;
	empty?: boolean | ArcWidgetKanbanEmpty;
	items?: ArcWidgetKanbanItem[];
	sections?: ArcWidgetKanbanSection[];
	scrollSettings?: ArcWidgetKanbanSwimlaneScrollSettings;
}

export interface ArcWidgetKanbanCollapsible {
	enabled?: boolean;
	defaultCollapsed?: boolean;
	iconExpand?: ArcWidgetSlot;
	iconCollapse?: ArcWidgetSlot;
}

export interface ArcWidgetKanbanStyles {
	minWidth?: string;
}

export interface ArcWidgetKanbanData {
	height?: string;
	empty?: boolean | ArcWidgetKanbanEmpty;
	swimlanes?: ArcWidgetKanbanSwimlane[];
	styles?: ArcWidgetKanbanStyles;
	scrollSettings?: ArcWidgetKanbanScrollSettings;
	scrollBar?: ArcWidgetKanbanScrollBar;
	collapsible?: boolean | ArcWidgetKanbanCollapsible;
	insetBorder?: boolean | ArcWidgetKanbanInsetBorder;
}

export interface ArcWidgetKanbanProps extends ArcReactWidgetProps<ArcWidgetKanbanData> {
	onItemClick?: (event: MouseEvent, payload: ArcWidgetKanbanItemClickPayload) => void;
	onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise<unknown>;
}
```

## 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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.
- **scrollBar**: `showScrollBar`, `height`, `backgroundColor`, `handle` (Look wie Tabelle, Track transparent). Standard ausgeblendet; `board` (horizontal) und `lanes` (vertikal) ändern nur eine Leiste. **styles.minWidth**: kleinste Breite aller Spalten; Spalten scrollen nie seitlich.
- **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.
- **Header slots**: `slotLeft` (before the title) and `slotRight` (after the count) per swimlane — icon, badge, or button. Use them instead of a nested title layout with `showAmount: false`.
- **Header without color**: `backgroundColorHeader: "transparent"` + dark `fontColor`. The drag outline keeps the dark default.

# Custom Kanban

![](https://framerusercontent.com/images/mHlFDpfOkhxieybe820lNfJs.png)

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 den Umschalter im Header ein- oder aufklappen kann. Der Umschalter ist ein Chevron, das sich beim Einklappen dreht.


```javascript
collapsible: true, // Aktiviert die Funktion
collapsible: "", // Fallback-Wert = "false"
```

Als Objekt nimmt `collapsible` auch eigene Icons für den Umschalter und den Startzustand. `iconExpand` zeigt sich, solange die Swimlane eingeklappt ist (ein Klick klappt auf), `iconCollapse`, solange sie offen ist (ein Klick klappt zu). Text, HTML-String oder verschachteltes Widget — wie `title`. Die Icons gelten auch für den Umschalter der Gruppen (`sections`).


```javascript
collapsible: {
    defaultCollapsed: false, // true: alle Swimlanes starten eingeklappt
    iconExpand: arcCustomIcon({ iconSet: "phosphor", name: "plus", iconSize: "14px" }),
    iconCollapse: arcCustomIcon({ iconSet: "phosphor", name: "minus", iconSize: "14px" })
}
```

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

Mit ***styles*** legst du die Maße des Kanbans fest. ***minWidth*** ist die Mindestbreite aller Swimlanes auf einmal. Die Swimlanes teilen sich die freie Breite gleichmäßig; würden sie schmaler, scrollt das Kanban seitlich (mit `scrollSettings.scrollX` einschalten). Ein `minWidth` an einer einzelnen Swimlane hat Vorrang.


```javascript
styles: { minWidth: "300px" }, // Pixel-Wert
styles: { minWidth: "" }, // Fallback-Wert: 150px
```

Mit ***scrollBar*** zeigst und gestaltest du die Scrollbars: die vertikale Leiste in jeder Swimlane und die horizontale Leiste des gesamten Kanbans unter den Swimlanes. Beide sind standardmäßig ausgeblendet, gescrollt wird trotzdem. Die Felder sind dieselben wie bei der Tabelle; der Track hat standardmäßig keine Farbe. `board` und `lanes` ändern nur eine der beiden Leisten.


```javascript
scrollBar: {
    showScrollBar: true, // false: ausgeblendet (Standard), Scrollen funktioniert trotzdem
    height: "8px",
    backgroundColor: "", // Track, Standard: ohne Farbe
    handle: { backgroundColor: "#9ca4a9", borderRadius: "5px" },
    board: { showScrollBar: true }, // nur die horizontale Leiste
    lanes: { showScrollBar: false } // nur die vertikalen Leisten
}
```

### 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: #18181b
```

***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: #f4f4f5
```

***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: "<b>" + cnt(list[number(Status) = number(id)]) + "</b>",
amount: "" // Kein Fallback-Wert. Die Amount-Bubble wird in diesem Fall ausgeblendet.
```

***slotLeft*** und ***slotRight*** setzen Inhalte in den Swimlane-Header: `slotLeft` vor den Titel, `slotRight` hinter die Zähler-Bubble. Text, HTML-String oder verschachteltes Widget — wie `title`. Typisch: links ein Status-Punkt, rechts ein Button. Klicks in einem Slot bleiben bei dessen Inhalt und klappen die Swimlane nicht ein.


```javascript
slotLeft: arcCustomIcon({ iconSet: "phosphor", name: "circle", style: "fill", color: text(color(Farbe)), iconSize: "10px" }),
slotRight: arcCustomButton({ uniqueId: "lane-add-" + Nr, title: "+", paddingX: "0.6em", paddingY: "0.3em", actions: [...] }),
slotLeft: "" // Kein Fallback-Wert. Der Slot wird in diesem Fall ausgeblendet.
```

Für einen **Header ohne Farbe** setzt du den Header transparent und die Schrift dunkel. Die Zähler-Bubble folgt der Schriftfarbe; der Rahmen beim Ziehen bleibt dunkel.


```javascript
backgroundColorHeader: "transparent",
fontColor: "#18181b",
```

### 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
```

***borderStroke*** definiert den Linienstil einer einseitigen Border (`borderPosition`). Die Linie wird mit runden Enden innerhalb der Karte gezeichnet und hält Abstand zu den abgerundeten Ecken. Ohne `borderPosition` hat sie keine Wirkung.

```javascript
borderStroke: "solid", // Fallback-Wert
borderStroke: "dashed",
borderStroke: "dotted",
```

Mit `borderPosition` ist die Linie standardmäßig `3px` breit; mit `borderWidth` änderst du das.

***insetBorder*** zeichnet eine in Segmente geteilte Linie in der Karte, z. B. eine Farbe pro Person. `position` (`left` ist der Standard, `right`, `top`, `bottom`), `width`, `stroke` und `color` gelten für die ganze Linie; `align` (`start`, `center`, `end`) platziert feste Segmente, die sie nicht füllen. Felder in `insetBorder` gewinnen gegen `borderPosition`, `borderColor`, `borderWidth` und `borderStroke`.

```javascript
insetBorder: {
    position: "left",
    width: "3px",
    stroke: "solid",
    color: "#18181B",   // Standard der Segmente
    segments: [
        { color: "#DC2626", label: "Anna" },                 // label = Tooltip
        { color: "#2563EB", label: "Ben", size: "24px" },    // feste Länge
        { color: "#16A34A", label: "Clara", stroke: "dashed" } // size: "fraction" (oder "auto") = Rest teilen
    ]
}
```

Die Linie ist standardmäßig an: Jede Karte zeigt eine schwarze Linie am linken Rand. `insetBorder: false` (oder `{ enabled: false }`) blendet sie aus; setzt du `insetBorder` in den Board-Daten, änderst du die Linie aller Karten auf einmal. Rangfolge: `insetBorder` des Boards, dann `borderPosition` / `borderColor` / `borderWidth` / `borderStroke`, dann das eigene `insetBorder` der Karte.

`size` ist `"fraction"` oder `"auto"` (beide teilen den Rest gleichmäßig, der Standard) oder eine Länge wie `"24px"` oder `"25%"`. Sind die festen Größen zusammen länger als die Linie, schrumpfen alle Segmente im gleichen Verhältnis. Die Linie sitzt 6px vom Kartenrand, der Text hält 8px Abstand.

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

```
<!-- /host -->


---

# Custom KPI Bar

Source: https://www.arc-rider.com/docs/widgets/custom-kpi-bar


<!-- host:react -->
# 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



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



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Eine Karte mit `clickable: true` wurde angeklickt. Liefert das DOM-Klick-Event und den nullbasierten Index der Karte in `cards`.

```typescript
onClick?: (event: MouseEvent, 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

Höhe der Leiste und Standard-Aussehen aller Karten: `height` (Standard `auto`), `colorLabel` (`#566eb1`), `fontSizeLabel` (`13px`), `colorValue` (`#3e6fff`), `fontSizeValue` (`35px`), `backgroundColor` (`#f7f8fc`), `borderColor` (`#e5e5e5`).

Typ: `ArcWidgetKpiBarSettings`.

### cards

Kennzahlenkarten in Anzeigereihenfolge: `title`, `value`, `subtitle`, `clickable` und `settings` je Karte. Die `settings` einer Karte überschreiben Farben und Schriftgrößen der Leiste und erlauben eine feste `width`.

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.

- `title`, `value` und `subtitle` werden als HTML-Strings dargestellt; JSX-Elemente und Widget-Deskriptoren werden hier nicht unterstützt. Fremden Text vor der Übergabe escapen.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: kpi_bar -->
```typescript
export interface ArcWidgetKpiBarCardSettings {
	colorLabel?: string;
	fontSizeLabel?: string;
	colorValue?: string;
	fontSizeValue?: string;
	backgroundColor?: string;
	borderColor?: string;
	width?: string;
}

export interface ArcWidgetKpiBarSettings {
	height?: string;
	colorLabel?: string;
	fontSizeLabel?: string;
	colorValue?: string;
	fontSizeValue?: string;
	backgroundColor?: string;
	borderColor?: string;
}

export interface ArcWidgetKpiBarCard {
	title?: string | number;
	value?: string | number;
	subtitle?: string | number;
	settings?: ArcWidgetKpiBarCardSettings;
	clickable?: boolean;
}

export interface ArcWidgetKpiBarData {
	settings?: ArcWidgetKpiBarSettings;
	cards?: ArcWidgetKpiBarCard[];
}

export interface ArcWidgetKpiBarProps extends ArcReactWidgetProps<ArcWidgetKpiBarData> {
	onClick?: (event: MouseEvent, 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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

![](https://framerusercontent.com/images/8Ouhx7SKhEFXPG22FsEV5i0g.png)

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:

![](https://framerusercontent.com/images/vgJSRSruJ02ARYRMMMm6yshxB0A.png)

## 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 (,).

<pre data-language="JavaScript"><code>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"
}]
    </code></pre>## 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

![](https://framerusercontent.com/images/vgJSRSruJ02ARYRMMMm6yshxB0A.png)


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

![](https://framerusercontent.com/images/al3UmQQbGCgJyxMk6N7cRKGowRw.png)


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

![](https://framerusercontent.com/images/8Ouhx7SKhEFXPG22FsEV5i0g.png)


```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)
<!-- /host -->


---

# Custom Layout

Source: https://www.arc-rider.com/docs/widgets/custom-layout


<!-- host:react -->
# Layout in React

Widgets und komplette Seiten horizontal oder vertikal anordnen. Beginne für neue Apps mit Arc Layout; HTML kann als Host und semantische Grenze bestehen bleiben. Ein eigener Host legt nur die Fensterhöhe fest, er muss das Seitenlayout nicht mit CSS Grid oder Flexbox nachbauen.

Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).

## Widget-First-App-Shell: AI Defaults

Für Sidebar, Kopfzeile und Inhalt nutze die [vollständige React-Vorlage](/docs/react/templates/react-starter), auch im Paket als `examples/blueprints/blueprint-app-shell.tsx`.

- Host: definierte Höhe, z. B. `100dvh`; verschachtelte Rahmen: `height: '100%'`.
- Vertikale Blöcke: Kopfzeile `height: 'auto'`, restlicher Inhalt `height: 'fraction'`.
- Scrollen: im restlichen Block ein Layout mit `height: '100%'` und `scrollSettings: { scrollY: true }`.
- Horizontale Blöcke: feste/automatische Sidebar-Breite, Hauptbereich `width: 'fraction'`.
- `min-width:0;min-height:0;` für begrenzte Blöcke; responsive Richtung und Größen zusammen umstellen.
- `fraction` als Block-Höhe nutzen, nicht als Höhe des inneren Layouts. Der Elternbereich muss eine definierte Höhe besitzen.

## Vollständiges Beispiel

<!-- react-example: layout-01-form_numbers.tsx -->
```tsx
import {
  ArcWidgetBadge,
  ArcWidgetInput,
  ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';

const row = (number: string, title: string) => ({
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        gap: '12px',
        height: '48px',
        blocks: [
          {
            width: '52px',
            value: (
              <ArcWidgetBadge
                data={{
                  value: number,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
          {
            width: 'fraction',
            value: (
              <ArcWidgetInput
                data={{
                  type: 'number',
                  labelSettings: { title },
                  numpad: { suffix: '€' },
                }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        gap: '8px',
        width: '420px',
        blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')],
      }}
    />
  );
}
```

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

<!-- react-example: layout-01-form_numbers.tsx -->
```tsx
import {
  ArcWidgetBadge,
  ArcWidgetInput,
  ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';

const row = (number: string, title: string) => ({
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        gap: '12px',
        height: '48px',
        blocks: [
          {
            width: '52px',
            value: (
              <ArcWidgetBadge
                data={{
                  value: number,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
          {
            width: 'fraction',
            value: (
              <ArcWidgetInput
                data={{
                  type: 'number',
                  labelSettings: { title },
                  numpad: { suffix: '€' },
                }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        gap: '8px',
        width: '420px',
        blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')],
      }}
    />
  );
}
```

### Rahmen, Trennlinie und Ecken

`border` am Layout zeichnet den Rahmen und rundet die Ecken. `border` an einem Block zeichnet nur die angegebenen `sides`, zum Beispiel eine Trennlinie unter einer Kopfzeile.

<!-- react-example: layout-02-border.tsx -->
```tsx
import { ArcWidgetLayout, ArcWidgetText } from '@arcrider/arcwidgets-react';

export default function Example() {
  // `border` on the Layout draws the card outline; `radius` rounds it.
  // `border` on a block draws only the listed `sides`: a divider under the header
  // and a dashed line above the total.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'stretch',
        alignY: 'top',
        width: '360px',
        height: 'auto',
        gap: '0px',
        backgroundColor: '#FFFFFF',
        border: { color: '#D4D4D8', radius: '12px' },
        blocks: [
          {
            paddingX: '16px',
            paddingY: '12px',
            border: { sides: ['bottom'] },
            value: (
              <ArcWidgetText
                data={{ value: 'Invoice AR-101', fontWeight: '700' }}
              />
            ),
          },
          {
            paddingX: '16px',
            paddingY: '12px',
            value: <ArcWidgetText data={{ value: 'Harbor Works' }} />,
          },
          {
            paddingX: '16px',
            paddingY: '12px',
            border: { sides: ['top'], style: 'dashed', color: '#A1A1AA' },
            value: (
              <ArcWidgetText data={{ value: 'Total: EUR 2,400', fontWeight: '700' }} />
            ),
          },
        ],
      }}
    />
  );
}
```

### Überlappung, wie bei einem Avatar-Stapel

Ein negativer `gap` überlappt die Blöcke um genau diesen Wert. `overlapOrder` bestimmt, welcher Block oben liegt: `end` (Standard) der letzte, `start` der erste, also in einer Reihe der linke und in einer Spalte der obere Block. Der Block unter dem Mauszeiger kommt immer nach vorne. Gib den Blöcken eine eigene Größe (`width: 'auto'` in einer Reihe), denn ein `fraction`-Block dehnt sich über die Überlappung.

<!-- react-example: layout-03-overlap.tsx -->
```tsx
import { ArcWidgetImage, ArcWidgetLayout, ArcWidgetText } from '@arcrider/arcwidgets-react';

// Generated square portraits keep the example offline.
const portrait = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    "<svg xmlns='http://www.w3.org/2000/svg' width='96' height='96'>" +
      `<rect width='96' height='96' fill='${color}'/>` +
      "<circle cx='48' cy='39' r='18' fill='#FFFFFF' fill-opacity='0.9'/>" +
      "<path d='M15 96 C15 71 81 71 81 96 Z' fill='#FFFFFF' fill-opacity='0.9'/>" +
      '</svg>',
  )}`;

const team = [
  { name: 'Alex Morgan', color: '#6366F1' },
  { name: 'Sam Lee', color: '#0EA5E9' },
  { name: 'Robin Diaz', color: '#F59E0B' },
  { name: 'Kim Novak', color: '#10B981' },
];

// One round portrait. The white ring separates it from the neighbor it overlaps.
const face = (member: (typeof team)[number]) => (
  <ArcWidgetImage
    data={{
      value: portrait(member.color),
      alt: member.name,
      title: member.name,
      width: '40px',
      height: '40px',
      objectFit: 'cover',
      loading: 'eager',
      border: { color: '#FFFFFF', width: '3px', radius: '50%' },
    }}
  />
);

// A negative `gap` pulls every block over its neighbor by that much. `overlapOrder` decides who lies on top:
// `end` (default) the last block, `start` the first one. The block under the pointer always comes to the front.
// Blocks need their own size here (`width: 'auto'` in a row, a fixed height in a column).
const stack = (direction: 'horizontal' | 'vertical', overlapOrder: 'start' | 'end') => (
  <ArcWidgetLayout
    data={{
      direction,
      alignX: 'center',
      height: 'auto',
      gap: '-12px',
      overlapOrder,
      blocks: team.map((member) => ({
        width: direction === 'horizontal' ? 'auto' : undefined,
        alignX: 'center',
        value: face(member),
      })),
    }}
  />
);

const card = (title: string, note: string, direction: 'horizontal' | 'vertical', overlapOrder: 'start' | 'end') => (
  <ArcWidgetLayout
    data={{
      direction: 'vertical',
      alignX: 'center',
      width: direction === 'horizontal' ? '280px' : '150px',
      height: 'auto',
      gap: '10px',
      paddingX: '16px',
      paddingY: '16px',
      backgroundColor: '#FFFFFF',
      border: { color: '#E4E4E7', radius: '12px' },
      blocks: [
        { value: <ArcWidgetText data={{ value: title, alignX: 'center', fontWeight: 700 }} /> },
        { value: <ArcWidgetText data={{ value: note, alignX: 'center', fontSize: '12px', fontColor: '#71717A' }} /> },
        { value: stack(direction, overlapOrder) },
      ],
    }}
  />
);

export default function Example() {
  // Two rows of faces, one stack on top of the other, then two columns side by side.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'top',
        height: 'auto',
        gap: '16px',
        paddingX: '16px',
        paddingY: '16px',
        backgroundColor: '#F4F4F5',
        border: { radius: '12px' },
        blocks: [
          { alignX: 'center', value: card('Last on top', 'Row · overlapOrder: end', 'horizontal', 'end') },
          { alignX: 'center', value: card('First on top', 'Row · overlapOrder: start', 'horizontal', 'start') },
          {
            alignX: 'center',
            value: (
              <ArcWidgetLayout
                data={{
                  direction: 'horizontal',
                  alignX: 'center',
                  alignY: 'top',
                  height: 'auto',
                  gap: '16px',
                  blocks: [
                    { width: 'auto', value: card('Last on top', 'Column · end', 'vertical', 'end') },
                    { width: 'auto', value: card('First on top', 'Column · start', 'vertical', 'start') },
                  ],
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Feuert, wenn ein Layout mit `clickable` außerhalb seiner Blöcke angeklickt wird. Klicks auf Blöcke kommen hier nie an.

```typescript
onClick?: () => void;
```

### onBlockClick

Feuert, wenn ein Block mit `clickable` angeklickt wird. `blockIndex` ist der nullbasierte Index in `data.blocks`.

```typescript
onBlockClick?: (blockIndex: number) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### direction

Richtung, in der die Blöcke angeordnet werden. Setze sie immer ausdrücklich. Standard: `vertical`.

Typ: `'horizontal' | 'vertical'`.

### alignX

Horizontale Platzierung der Blöcke. `between` wirkt nur bei `direction: 'horizontal'`, `stretch` nur bei `'vertical'`. Standard: `center`.

Typ: `'left' | 'center' | 'right' | 'between' | 'stretch'`.

### alignY

Vertikale Platzierung der Blöcke. `between` wirkt nur bei `direction: 'vertical'`, `stretch` nur bei `'horizontal'`. Standard: `center`.

Typ: `'top' | 'center' | 'bottom' | 'between' | 'stretch'`.

### width

Breite des Layouts. `'fraction'` füllt die verbleibende Breite des umgebenden Blocks; jeder andere Wert ist CSS. Standard: `100%`.

Typ: `'fraction' | (string & {})`.

### height

Höhe des Layouts als CSS, z. B. `"320px"`. Nutze einen festen Wert für scrollbare Shells und `'auto'` für Layouts, die sich nach dem Inhalt richten. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe. Standard: `100%`.

Typ: `string`.

### gap

Abstand zwischen den Blöcken. Standard: `2px`. Ein negativer Wert, zum Beispiel `'-8px'`, überlappt die Blöcke um diesen Wert. Blöcke mit `width: 'fraction'` (oder `height: 'fraction'` in einer Spalte) dehnen sich über die Überlappung, überlappende Blöcke brauchen deshalb eine eigene Größe.

Typ: `string`.

### overlapOrder

Welcher Block oben liegt, wenn `gap` negativ ist: `'end'` der letzte Block, `'start'` der erste Block (links in einer Reihe, oben in einer Spalte). Der Block unter dem Mauszeiger kommt immer nach vorne. Standard: `end`.

Typ: `'start' | 'end'`.

### backgroundColor

Hintergrundfarbe.

Typ: `string`.

### minWidth

Kleinste Breite des Layouts als CSS, z. B. `"320px"`. Das Layout wird nie schmaler; der umgebende Bereich scrollt oder schneidet stattdessen ab. Auch Blöcke nehmen `minWidth`.

Typ: `string`.

### maxWidth

Größte Breite des Layouts als CSS, z. B. `"1000px"`. Ein Layout mit `maxWidth` wird im Elternbereich horizontal zentriert; so entsteht eine Seitenspalte ohne zusätzliches CSS. Auch Blöcke nehmen `maxWidth` (z. B. `"100%"`, damit ein breites Kind im Block bleibt); ein Block wird über das `alignX` seines Layouts positioniert.

Typ: `string`.

### border

Rahmen und Eckenradius des Layout-Containers: `color`, `width`, `style`, `radius` und `sides`. Die Linie wird gezeichnet, sobald `color`, `width`, `style` oder `sides` gesetzt ist; `radius` allein rundet nur die Ecken. Kinder werden vom Radius nicht abgeschnitten, gib einem farbigen inneren Block deshalb denselben Radius. Blöcke nehmen dasselbe `border`-Objekt.

Typ: `ArcWidgetLayoutBorder`.

### paddingX

Innerer Abstand links und rechts.

Typ: `string`.

### paddingY

Innerer Abstand oben und unten.

Typ: `string`.

### lineHeight

Zeilenhöhe, die die Blöcke erben.

Typ: `string`.

### scrollSettings

Scrollen des Layout-Containers (`scrollX`, `scrollY`). Scrollleisten bleiben ausgeblendet; `scrollY` braucht eine feste `height`.

Typ: `ArcWidgetLayoutScrollSettings`.

### styles

Rohe CSS-Deklarationen, die zuletzt auf den Layout-Container angewendet werden, z. B. `'padding: 8px; color: #333'`.

Typ: `string`.

### clickable

`true` zeigt einen Zeiger-Cursor und löst `onClick` bei Klicks außerhalb der Blöcke aus. Standard: `false`.

Typ: `boolean`.

### blocks

Zeilen (vertikal) oder Spalten (horizontal) des Layouts. Jeder Block hat eigene Größe, Ausrichtung (`alignX`, `alignY`), Farben, `styles` und Inhalt in `value`; siehe `ArcWidgetLayoutBlock`.

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.

- Jeder Block ist ein horizontaler Flex-Container. Positioniere seinen Inhalt mit `blocks[].alignX` (`left`, `center`, `right`; Standard `left`) und `blocks[].alignY` (`top`, `center`, `bottom`, `stretch`; Standard `center`). `text-align` in `blocks[].styles` kann den Inhalt nicht zentrieren.

- `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 ganzseitige Layouts gibst du dem umgebenden App-Element eine feste Höhe wie `100dvh`.

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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: layout -->
```typescript
export interface ArcWidgetLayoutBorder {
	color?: string;
	width?: string;
	style?: 'solid' | 'dashed' | 'dotted' | 'double';
	radius?: string;
	sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}

export interface ArcWidgetLayoutBlock {
	value?: ArcWidgetSlot;
	width?: 'fraction' | (string & {});
	minWidth?: string;
	maxWidth?: string;
	height?: 'fraction' | (string & {});
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom' | 'stretch';
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetLayoutBorder;
	color?: string;
	backgroundImage?: string;
	backgroundSize?: string;
	backgroundPosition?: string;
	lineHeight?: string;
	styles?: string;
	clickable?: boolean;
	blockId?: string;
}

export interface ArcWidgetLayoutScrollSettings {
	scrollX?: boolean;
	scrollY?: boolean;
}

export interface ArcWidgetLayoutData {
	direction?: 'horizontal' | 'vertical';
	alignX?: 'left' | 'center' | 'right' | 'between' | 'stretch';
	alignY?: 'top' | 'center' | 'bottom' | 'between' | 'stretch';
	width?: 'fraction' | (string & {});
	minWidth?: string;
	maxWidth?: string;
	height?: string;
	gap?: string;
	overlapOrder?: 'start' | 'end';
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetLayoutBorder;
	lineHeight?: string;
	scrollSettings?: ArcWidgetLayoutScrollSettings;
	styles?: string;
	clickable?: boolean;
	blocks?: ArcWidgetLayoutBlock[];
}

export interface ArcWidgetLayoutProps extends ArcReactWidgetProps<ArcWidgetLayoutData> {
	onClick?: () => void;
	onBlockClick?: (blockIndex: 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)
<!-- /host -->

<!-- host:ninox -->
# 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

![](https://framerusercontent.com/images/aFEbrJb3sdVWKcqtanFF6Fd1L1I.png)

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.

<iframe src="https://www.youtube.com/embed/vVciopAN3Dw?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>

## 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.
```

<iframe src="https://www.youtube.com/embed/7pxvuLLhbkY?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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
```

<iframe src="https://www.youtube.com/embed/VW8ycZiNM2Y?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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.

![](https://framerusercontent.com/images/Vkymdh6PJgSU5aZU3b6Bun2Uk4s.png)


```javascript
gap: "5px", // Pixel-Werte
```

Mit einem negativen ***gap*** überlappen sich die ***blocks***, wie bei einem Avatar-Stapel. ***overlapOrder*** bestimmt, welcher Block oben liegt: `"end"` (Standard) der letzte, `"start"` der erste (links in einer Reihe, oben in einer Spalte).

```javascript
gap: "-8px", // 8 Pixel überlappen
overlapOrder: "start", // der erste Block liegt oben
```

### minWidth / maxWidth

Mit ***minWidth*** und ***maxWidth*** legst du die kleinste und größte Breite des Layouts fest. Ein Layout mit ***maxWidth*** wird im Elternbereich horizontal zentriert.

```javascript
minWidth: "320px", // default: keine
maxWidth: "1000px", // default: keine
```

### border

Mit ***border*** gibst du dem Layout einen Rahmen und runde Ecken. Die Linie wird gezeichnet, sobald ***color***, ***width***, ***style*** oder ***sides*** gesetzt ist; ***radius*** allein rundet nur die Ecken. Kinder werden vom Radius nicht abgeschnitten, gib einem farbigen inneren Block deshalb denselben Radius.

```javascript
border: {
  color: "#D4D4D8", // default: #EBEDF5
  width: "1px", // default: 1px
  style: "solid", // solid | dashed | dotted | double
  radius: "12px", // default: 0
  sides: ["top", "right", "bottom", "left"], // default: all four
},
```

### 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
```

### minWidth / maxWidth

Mit ***minWidth*** und ***maxWidth*** legst du die kleinste und größte Breite eines Layout-Blocks fest, z. B. `maxWidth: "100%"`, damit ein breites Kind im Block bleibt.

```javascript
minWidth: "240px", // default: keine
maxWidth: "480px", // default: keine
```

### border

***border*** funktioniert an einem Layout-Block genauso. Mit ***sides*** zeichnest du nur einzelne Seiten, zum Beispiel eine Trennlinie unter einem Kopfblock.

```javascript
border: {
  sides: ["bottom"], // only the bottom line
  color: "#EBEDF5",
},
```

### 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,
```
<!-- /host -->

<!-- host:vue -->
# 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

![](https://framerusercontent.com/images/aFEbrJb3sdVWKcqtanFF6Fd1L1I.png)

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.

<iframe src="https://www.youtube.com/embed/vVciopAN3Dw?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>

## 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.
```

<iframe src="https://www.youtube.com/embed/7pxvuLLhbkY?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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
```

<iframe src="https://www.youtube.com/embed/VW8ycZiNM2Y?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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.

![](https://framerusercontent.com/images/Vkymdh6PJgSU5aZU3b6Bun2Uk4s.png)


```javascript
gap: "5px", // Pixel-Werte
```

Mit einem negativen ***gap*** überlappen sich die ***blocks***, wie bei einem Avatar-Stapel. ***overlapOrder*** bestimmt, welcher Block oben liegt: `"end"` (Standard) der letzte, `"start"` der erste (links in einer Reihe, oben in einer Spalte).

```javascript
gap: "-8px", // 8 Pixel überlappen
overlapOrder: "start", // der erste Block liegt oben
```

### minWidth / maxWidth

Mit ***minWidth*** und ***maxWidth*** legst du die kleinste und größte Breite des Layouts fest. Ein Layout mit ***maxWidth*** wird im Elternbereich horizontal zentriert.

```javascript
minWidth: "320px", // default: keine
maxWidth: "1000px", // default: keine
```

### border

Mit ***border*** gibst du dem Layout einen Rahmen und runde Ecken. Die Linie wird gezeichnet, sobald ***color***, ***width***, ***style*** oder ***sides*** gesetzt ist; ***radius*** allein rundet nur die Ecken. Kinder werden vom Radius nicht abgeschnitten, gib einem farbigen inneren Block deshalb denselben Radius.

```javascript
border: {
  color: "#D4D4D8", // default: #EBEDF5
  width: "1px", // default: 1px
  style: "solid", // solid | dashed | dotted | double
  radius: "12px", // default: 0
  sides: ["top", "right", "bottom", "left"], // default: all four
},
```

### 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
```

### minWidth / maxWidth

Mit ***minWidth*** und ***maxWidth*** legst du die kleinste und größte Breite eines Layout-Blocks fest, z. B. `maxWidth: "100%"`, damit ein breites Kind im Block bleibt.

```javascript
minWidth: "240px", // default: keine
maxWidth: "480px", // default: keine
```

### border

***border*** funktioniert an einem Layout-Block genauso. Mit ***sides*** zeichnest du nur einzelne Seiten, zum Beispiel eine Trennlinie unter einem Kopfblock.

```javascript
border: {
  sides: ["bottom"], // only the bottom line
  color: "#EBEDF5",
},
```

### 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
<ArcWidgetLayout id="shell" :data="layoutData" @action="handleAction" />
```
<!-- /host -->


---

# 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

![](https://framerusercontent.com/images/OTLGI4WPfhC5wvwpr6txpt5tjW4.png)

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**</p><p>Direkt auf oberster Ebene (`uniqueId`, `embedded`, `hoverActions`)
- **Menü-Konfiguration (**`**menu[…]**`**)**</p><p>Steuert das Layout der Menüleiste – z. B. Positionierung, Schriftgröße und Farben für normale und aktive Zustände
- **Menüpunkte (**`**menu[…].menuItems[…]**`**)**</p><p>Einzelne Buttons mit Titel, Icon, Aktivitätszustand und Aktionen (z. B. Feldwert ändern, Popup öffnen)

<iframe src="https://www.youtube.com/embed/vydo4Vmmjig?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>
```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"
                            }]
                    }]
            }]
    })
```

![](https://framerusercontent.com/images/9Pma4rkrUgqREGiOmgEUKOQ5nY.png)

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

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`backgroundColor`

</td><td>`text`

</td><td>Hintergrundfarbe beim Hover. Z. B.  HEX-Wert: `"#192e65"`

</td></tr><tr><td>`fontColor`

</td><td>`text`

</td><td>Schriftfarbe beim Hover. Z. B.  HEX-Wert: `"#fff"`

</td></tr><tr><td>`borderColor`

</td><td>`text`

</td><td>Rahmenfarbe beim Hover. Z. B.  HEX-Wert: `"#192e65"`

</td></tr><tr><td>`iconColor`

</td><td>`text`

</td><td>Farbe des Icons beim Hover. Z. B.  HEX-Wert:`"#fff"`

</td></tr><tr><td>`animation`

</td><td>`text`

</td><td>Transition-Zeit, z. B. `"0.2s"` für weiche Effekte

</td></tr></tbody></table></figure>💡 **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.

<iframe src="https://www.youtube.com/embed/J4NAQ1PbggU?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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

<figure><table><tbody><tr><th>`type`

</th><th>Beschreibung

</th><th>Aufbau Code

</th></tr><tr><td>`update`

</td><td>Setzt den Wert eines Feldes im angegebenen Datensatz

</td><td>`recordId`, `field`, `value`

</td></tr><tr><td>`popup`

</td><td>Öffnet den angegebenen Datensatz als Popup

</td><td>`recordId`

</td></tr><tr><td>`delete`

</td><td>Löscht den angegebenen Datensatz aus der Datenbank

</td><td>`recordId`

</td></tr></tbody></table></figure>### 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


<!-- host:react -->
# 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



## Features ausprobieren

### Dezimalstellen, Suffix und Tastatureingabe

Teste Ganzzahlen und Dezimalwerte. Tastaturereignisse gelten nur innerhalb der geöffneten Live-Vorschau; Enter übernimmt den Wert.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Die Eingabe wurde abgeschickt. `value` ist ein Zahlen-String mit Punkt als Dezimaltrenner und ohne nachgestellte Nullen, z. B. `"12.5"`; eine leere Eingabe ergibt `"0"`.

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

Startwert mit Punkt oder `decimalSeparator` als Dezimaltrenner, z. B. `12.5` oder `"12,5"`.

Typ: `string | number`.

### actionTitle

Beschriftung des Absenden-Buttons. Standard: `Submit`.

Typ: `string`.

### backgroundColor

Farbe der Tasten und des Absenden-Buttons; Hex-Farben erhalten zusätzlich einen helleren Gedrückt-Zustand. Standard: `#007bff`.

Typ: `string`.

### fontColor

Textfarbe der Tasten und des Absenden-Buttons. Standard: `#ffffff`.

Typ: `string`.

### display

Anzeige über den Tasten: `fontColor` (Standard `#000000`) und `height` als maximale Höhe.

Typ: `ArcWidgetNumpadDisplay`.

### suffix

Einheit hinter dem Wert, z. B. `"kg"`.

Typ: `string`.

### clearOnFirstInput

Ersetzt `currentValue` durch die erste getippte Ziffer, statt anzuhängen. Standard: `false`.

Typ: `boolean`.

### decimalSeparator

Dezimaltrenner auf der Taste und in der Anzeige. Standard: `,`.

Typ: `'.' | ','`.

### maxDecimals

Maximale Anzahl Nachkommastellen; ohne Angabe unbegrenzt.

Typ: `number`.

### keyboard

Eingabe über die physische Tastatur, solange dieses Numpad zuletzt benutzt wurde: Ziffern, `,` / `.`, Backspace, Entf oder Escape zum Leeren, Enter zum Absenden. `true` schaltet sie ein; ein Objekt setzt `enabled` (Standard `true`) und `submitOnEnter` (Standard `true`). Standardmäßig aus.

Typ: `boolean | ArcWidgetNumpadKeyboard`.

## Verhalten und Grenzen

- `onSubmit` liefert unabhängig von `decimalSeparator` einen String mit Punkt als Dezimaltrenner, z. B. `"12.5"`. Wandle ihn mit `Number(value)` um und prüfe das Ergebnis.

- `currentValue` befüllt die Anzeige. `clearOnFirstInput` ist hilfreich, wenn ein bestehender Wert überschrieben wird.

- Tastatureingaben werden ignoriert, solange ein Textfeld oder ein anderes editierbares Element den Fokus hat.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: numpad -->
```typescript
export interface ArcWidgetNumpadDisplay {
	fontColor?: string;
	height?: string;
}

export interface ArcWidgetNumpadKeyboard {
	enabled?: boolean;
	submitOnEnter?: boolean;
}

export interface ArcWidgetNumpadData {
	currentValue?: string | number;
	actionTitle?: string;
	backgroundColor?: string;
	fontColor?: string;
	display?: ArcWidgetNumpadDisplay;
	suffix?: string;
	clearOnFirstInput?: boolean;
	decimalSeparator?: '.' | ',';
	maxDecimals?: number;
	keyboard?: boolean | ArcWidgetNumpadKeyboard;
}

export interface ArcWidgetNumpadProps extends ArcReactWidgetProps<ArcWidgetNumpadData> {
	onSubmit?: (value: string) => void;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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`)
<!-- /host -->


---

# Custom Slider

Source: https://www.arc-rider.com/docs/widgets/custom-slider


<!-- host:react -->
# 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



## Features ausprobieren

### Schrittweite und gemeinsamer State

Der Slider steuert den Fortschrittsbalken über denselben State. Ändere die Schrittweite und verschiebe den Regler.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Der Griff wurde losgelassen oder die Spur angeklickt. Liefert den neuen Wert; übernimm ihn 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

Aktueller Wert, begrenzt auf `min`…`max`. Standard: `min`.

Typ: `number`.

### min

Kleinster Wert. Standard: `0`.

Typ: `number`.

### max

Größter Wert. Standard: `100`.

Typ: `number`.

### step

Schrittweite beim Ziehen und beim Klick auf die Spur. Standard: `1`.

Typ: `number`.

### width

Breite des Widgets, z. B. `"300px"`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"40px"`.

Typ: `string`.

### track

Aussehen der Spur: `height`, `backgroundColor`, `borderRadius`.

Typ: `ArcWidgetSliderTrackStyle`.

### fill

Aussehen des gefüllten Bereichs: `backgroundColor`.

Typ: `ArcWidgetSliderFillStyle`.

### thumb

Aussehen des Griffs: `width`, `height`, `backgroundColor`, `borderColor`, `borderWidth`, `borderRadius`.

Typ: `ArcWidgetSliderThumbStyle`.

### valueDisplay

Aktueller Wert neben dem Slider: `show` (Standard `true`), `color`, `fontSize`.

Typ: `ArcWidgetSliderValueDisplay`.

### statusDisplay

Status-Einträge je Wertebereich. Ein Eintrag gilt, solange der Wert mindestens seinem `value` entspricht; der höchste passende Eintrag gewinnt, zeigt sein `label` in `color` und überschreibt `track`, `fill` und `thumb`.

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`. Das Widget speichert nichts selbst; behalte den Wert in deinem State.


## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: slider -->
```typescript
export interface ArcWidgetSliderTrackStyle {
	height?: string;
	backgroundColor?: string;
	borderRadius?: string;
}

export interface ArcWidgetSliderFillStyle {
	backgroundColor?: string;
}

export interface ArcWidgetSliderThumbStyle {
	width?: string;
	height?: string;
	backgroundColor?: string;
	borderColor?: string;
	borderWidth?: string;
	borderRadius?: string;
}

export interface ArcWidgetSliderValueDisplay {
	show?: boolean;
	color?: string;
	fontSize?: string;
}

export interface ArcWidgetSliderStatusDisplay {
	value: number;
	label: string;
	color?: string;
	track?: ArcWidgetSliderTrackStyle;
	fill?: ArcWidgetSliderFillStyle;
	thumb?: ArcWidgetSliderThumbStyle;
}

export interface ArcWidgetSliderData {
	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<ArcWidgetSliderData> {
	onChange?: (value: number) => void;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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).

<figure><table><tbody><tr><th>Feld

</th><th>Beschreibung

</th></tr><tr><td>`height`

</td><td>Höhe des Tracks, z. B. `"6px"`

</td></tr><tr><td>`backgroundColor`

</td><td>Farbe des Tracks, z. B. `"#E9ECF4"`

</td></tr><tr><td>`borderRadius`

</td><td>Border-Radius des Tracks, z. B. `"3px"`

</td></tr></tbody></table></figure>

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

<figure><table><tbody><tr><th>Feld

</th><th>Beschreibung

</th></tr><tr><td>`width` / `height`

</td><td>Größe des Knopfs, z. B. `"20px"`

</td></tr><tr><td>`backgroundColor`

</td><td>Füllfarbe des Knopfs

</td></tr><tr><td>`borderColor` / `borderWidth` / `borderRadius`

</td><td>Rahmen des Knopfs, z. B. `borderRadius: "50%"` für rund

</td></tr></tbody></table></figure>

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

<figure><table><tbody><tr><th>Feld

</th><th>Beschreibung

</th></tr><tr><td>`label`

</td><td>Icon oder Text, z. B. `"🔥"`, `"✓"`, `"⚠"`, `"✕"`

</td></tr><tr><td>`value`

</td><td>Schwellenwert – ab diesem Wert wird der Status aktiv

</td></tr><tr><td>`color`

</td><td>Farbe des Icon-Texts

</td></tr><tr><td>`track` / `fill` / `thumb`

</td><td>Optional: gleiche Struktur wie oben, überschreibt das Standard-Styling für diesen Status (mit `!important`)

</td></tr></tbody></table></figure>

```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.
<!-- /host -->


---

# Custom Slideshow

Source: https://www.arc-rider.com/docs/widgets/custom-slideshow


<!-- host:react -->
# 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



## Features ausprobieren

### Richtung, Schleife und Autoplay

Teste Pfeile, Punkte und die automatische Wiedergabe. Die Folien verwenden feste HTML-Strings; JSX ist in Slideshow-Inhalten nicht unterstützt.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

### data

Konfiguration vom Typ `ArcWidgetSlideshowData`. Ü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).

### onSlideChange

Der aktive Slide hat gewechselt. Liefert den nullbasierten `index` in `items`.

```typescript
onSlideChange?: (payload: ArcWidgetSlideshowSlideChangePayload) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### items

Slides in Anzeigereihenfolge. `value` ist reiner Text, ein HTML-String oder `<image src=…>` für ein Bild in voller Größe; `label` ist der Alternativtext. Optional je Slide: `width`, `height`, `backgroundColor`.

Typ: `ArcWidgetSlideshowItem[]`.

### width

Breite des Widgets. Standard: `100%`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe. Standard: `300px`.

Typ: `string`.

### backgroundColor

Hintergrundfarbe hinter den Slides. Standard: `#f5f5f5`.

Typ: `string`.

### borderRadius

Eckenradius. Standard: `8px`.

Typ: `string`.

### borderWidth

Rahmenbreite, z. B. `"1px"`. Standard: `0px`.

Typ: `string`.

### borderColor

Rahmenfarbe. Standard: `transparent`.

Typ: `string`.

### direction

Laufrichtung der Slides. Standard: `horizontal`.

Typ: `'horizontal' | 'vertical'`.

### loop

Springt vom letzten Slide zum ersten und zurück. Standard: `true`.

Typ: `boolean`.

### autoplay

Automatischer Wechsel: `enabled` und `speed` in Millisekunden zwischen zwei Slides. Standardmäßig aus.

Typ: `ArcWidgetSlideshowAutoplay`.

### pause

Pausiert den automatischen Wechsel bei `hover` oder `focus`. Ohne `pause` gilt beides; in deinem Objekt fehlende Keys zählen als `false`.

Typ: `ArcWidgetSlideshowPause`.

### transition

Slide-Animation: `duration` in Millisekunden und die CSS-Easing-Funktion in `transition`. Standard: `{ duration: 300, transition: 'ease-in-out' }`.

Typ: `ArcWidgetSlideshowTransition`.

### indicators

`enabled` zeigt einen Punkt je Slide. Ohne `indicators` werden die Punkte angezeigt.

Typ: `ArcWidgetSlideshowIndicators`.

## Verhalten und Grenzen

- `items[].value` unterstützt derzeit Strings, einschließlich eigenem HTML. JSX und verschachtelte Widget-Deskriptoren werden in dieser Komponente nicht gerendert.

- `autoplay.speed` und `transition.duration` werden in Millisekunden angegeben. `onSlideChange` liefert einen nullbasierten `index`.

- Das Galerie-Beispiel verwendet selbst erzeugte SVG-Bilder. HTML mit dynamischen, fremden Inhalten muss vor Übergabe bereinigt werden.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: slideshow -->
```typescript
export interface ArcWidgetSlideshowItem {
	value?: string;
	label?: string;
	width?: string;
	height?: string;
	backgroundColor?: string;
}

export interface ArcWidgetSlideshowAutoplay {
	enabled?: boolean;
	speed: number;
}

export interface ArcWidgetSlideshowPause {
	hover?: boolean;
	focus?: boolean;
}

export interface ArcWidgetSlideshowTransition {
	duration: number;
	transition: 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear' | (string & {});
}

export interface ArcWidgetSlideshowIndicators {
	enabled?: boolean;
}

export interface ArcWidgetSlideshowData {
	items: ArcWidgetSlideshowItem[];
	width?: string;
	height?: string;
	backgroundColor?: string;
	borderRadius?: string;
	borderWidth?: string;
	borderColor?: string;
	direction?: 'horizontal' | 'vertical';
	loop?: boolean;
	autoplay?: ArcWidgetSlideshowAutoplay;
	pause?: ArcWidgetSlideshowPause;
	transition?: ArcWidgetSlideshowTransition;
	indicators?: ArcWidgetSlideshowIndicators;
}

export interface ArcWidgetSlideshowSlideChangePayload {
	index: number;
}

export interface ArcWidgetSlideshowProps extends ArcReactWidgetProps<ArcWidgetSlideshowData> {
	onSlideChange?: (payload: ArcWidgetSlideshowSlideChangePayload) => void;
}
```

## Einsatzbeispiele

- [Bildergalerie mit Slideshow](/docs/react/examples/image-slider)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Slideshow

## AI Defaults (read first)

- **Function name**: `arcCustomSlideshow`.
- **items**: Required array – each item needs at least `value` (Text, HTML-String, or `<image ...>`-HTML). Without `items` the slideshow renders empty.
- **width / height**: Default `"100%"` / `"300px"` – set explicitly when not embedded.
- **embedded**: Default `false`. Set `true` when nesting inside `arcCustomLayout` etc. – the slideshow then fills `100%`/`100%` of its parent instead of using `width`/`height`.
- **direction**: `"horizontal"` (default) or `"vertical"` – controls both the slide track and swipe/drag direction.
- **loop**: Default `true` – set `false` to stop at the first/last slide.
- **autoplay**: Default `{ enabled: false, speed: 3000 }` – only starts if `enabled: true`.
- **Not yet wired up**: `controls.enabled`, `indicators.type`, `indicators.position`, top-level `scroll`, and `pause.scroll` / `pause.click` / `pause.touch` are accepted in `data` but currently have **no effect** – nav arrows and dot indicators are always shown, dots are always at the bottom (horizontal) / right (vertical). Only `pause.hover` and `pause.focus` actually pause autoplay. Don't rely on these for a client build without re-checking the code.
- **uniqueId**: Not required by this widget (unlike most others) – the container `id` passed by the adapter is used directly.

# Custom Slideshow

Mit `arcCustomSlideshow` baust du eine Bildergalerie / Slideshow direkt in Ninox – mit Swipe-Geste (Touch & Maus-Drag), Pfeil-Navigation, Punkt-Indikatoren und optionalem Autoplay. Es eignet sich für Bildergalerien, Produktvorschauen oder einfache Text-Slides innerhalb eines Dashboards oder Layouts.

**Das kannst du steuern:**

- Ausrichtung (horizontal / vertikal)
- Größe, Rahmen, Hintergrundfarbe des Containers
- Autoplay (an/aus, Geschwindigkeit)
- Loop-Verhalten an den Rändern
- Übergangs-Animation (Dauer, Easing)
- Inhalt jedes einzelnen Slides (Text, HTML, Bild)

## Anwendungscode

```javascript
arcCustomSlideshow({
    embedded: false,
    width: "100%",
    height: "400px",
    backgroundColor: "#f5f5f5",
    borderRadius: "8px",
    borderWidth: "0px",
    borderColor: "transparent",
    direction: "horizontal",
    loop: true,
    autoplay: {
        enabled: true,
        speed: 4000
    },
    pause: {
        hover: true,
        focus: true
    },
    transition: {
        duration: 300,
        transition: "ease-in-out"
    },
    indicators: {
        enabled: true
    },
    items: [{
            value: "<image value=\"" + shareFile(record(Bilder, 1).Bild) + "\">",
            label: "Bild 1"
        }, {
            value: "<image value=\"" + shareFile(record(Bilder, 2).Bild) + "\">",
            label: "Bild 2"
        }, {
            value: "Ein einfacher Text-Slide",
            backgroundColor: "#e3f2fd"
        }]
})
```

## Parameter

### embedded

**Typ:** `boolean`
**Default:** `false`

Bestimmt, ob die Slideshow **eingebettet** in ein anderes Widget (z. B. `arcCustomLayout`) dargestellt wird oder **eigenständig** auf der Oberfläche steht.

- `true` → Slideshow füllt `100%` Breite/Höhe des umgebenden Containers.
- `false` → Slideshow verwendet `width` / `height` direkt.

### width / height

**Typ:** `text`
**Default:** `"100%"` / `"300px"`

Breite und Höhe der Slideshow, wenn `embedded: false`. Bei `embedded: true` werden diese Werte ignoriert (immer `100%`/`100%`).

```javascript
width: "100%",
height: "400px",
```

### backgroundColor / borderRadius / borderWidth / borderColor

**Typ:** `text`
**Default:** `"#f5f5f5"` / `"8px"` / `"0px"` / `"transparent"`

Styling des Slideshow-Containers (nicht der einzelnen Slides).

```javascript
backgroundColor: "#f5f5f5",
borderRadius: "8px",
borderWidth: "1px",
borderColor: "#ddd",
```

### direction

**Typ:** `text`
**Default:** `"horizontal"`

Legt fest, ob Slides horizontal (nebeneinander, Swipe links/rechts) oder vertikal (untereinander, Swipe hoch/runter) angeordnet sind. Die Pfeil-Buttons und Punkt-Indikatoren passen ihre Position automatisch an.

```javascript
direction: "horizontal", // Standard – Pfeile links/rechts
direction: "vertical",   // Pfeile oben/unten
```

### loop

**Typ:** `boolean`
**Default:** `true`

- `true` → Nach dem letzten Slide geht es zurück zum ersten (und umgekehrt).
- `false` → Am ersten/letzten Slide stoppt die Navigation (kein Wrap-around).

### Block: autoplay{}

**Typ:** `object`
**Default:** `{ enabled: false, speed: 3000 }`

```javascript
autoplay: {
    enabled: true,
    speed: 4000 // ms zwischen den Slides
}
```

### Block: pause{}

**Typ:** `object`
**Default:** `{ hover: true, focus: true, scroll: true, click: true, touch: true }`

⚠️ **Nur `hover` und `focus` sind aktuell implementiert.** `scroll`, `click`, `touch` werden zwar entgegengenommen, pausieren das Autoplay aber (noch) nicht.

```javascript
pause: {
    hover: true, // Autoplay pausiert, solange die Maus über der Slideshow ist
    focus: true  // Autoplay pausiert, solange die Slideshow fokussiert ist (z. B. per Tab-Taste)
}
```

### Block: transition{}

**Typ:** `object`
**Default:** `{ duration: 300, delay: 0, transition: "ease-in-out" }`

Steuert die Animation beim Wechsel zwischen Slides. `delay` wird aktuell nicht ausgewertet.

```javascript
transition: {
    duration: 300,           // ms
    transition: "ease-in-out" // CSS-Timing-Funktion
}
```

### Block: indicators{}

**Typ:** `object`
**Default:** `{ enabled: true, type: "dots", position: "bottom" }`

⚠️ Nur `enabled` hat aktuell einen Effekt (Punkte ein-/ausblenden). `type` und `position` sind reserviert für spätere Erweiterungen.

```javascript
indicators: {
    enabled: true // false blendet die Punkt-Navigation komplett aus
}
```

### items

**Typ:** `array of objects`
**Pflichtfeld**

Jeder Eintrag beschreibt einen Slide.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`value`

</td><td>`text`

</td><td>Inhalt des Slides: einfacher Text, HTML-String (`<div>…</div>`), oder ein `<image value="...">`-HTML-Fragment (z. B. Ergebnis von `shareFile()`).

</td></tr><tr><td>`label`

</td><td>`text`

</td><td>Fallback-Text, falls `value` leer ist oder kein String – z. B. `"Slide 1"`.

</td></tr><tr><td>`width` / `height`

</td><td>`text`

</td><td>Größe des einzelnen Slides (Default: `100%` / `100%`).

</td></tr><tr><td>`backgroundColor`

</td><td>`text`

</td><td>Individuelle Hintergrundfarbe für diesen Slide.

</td></tr></tbody></table></figure>

```javascript
items: [{
    value: "<image value=\"" + shareFile(record(Bilder, 1).Bild) + "\">",
    label: "Bild 1"
}, {
    value: "Nur Text als Slide",
    backgroundColor: "#e3f2fd"
}]
```

💡 **Tipp:** Für eine echte Bildergalerie aus einer Ninox-Tabelle baue `items` per `for`-Schleife über deine Bilder-Tabelle auf (z. B. mit `shareFile()` pro Datensatz), statt die Slides einzeln fest zu codieren.

## Verwandtes Widget

Für einen klassischen **Wertregler** (z. B. Prozent- oder Zahlenwert per Ziehen einstellen) verwendest du stattdessen [`arcCustomSlider`](/documentation/custom-slider) – das ist ein eigenständiges Widget und hat mit der Bild-/Content-Slideshow nichts zu tun.
<!-- /host -->


---

# Custom Steps

Source: https://www.arc-rider.com/docs/widgets/custom-steps


<!-- host:react -->
# Steps in React

Den Fortschritt in einem mehrstufigen Formular anzeigen. Navigation und Validierung steuerst du in React.

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



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



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Der Wert eines Schritts mit `clickable: true` wurde angeklickt. Liefert das DOM-Klick-Event und den nullbasierten Index des Schritts in `steps`.

```typescript
onClick?: (event: MouseEvent, 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

Layout und Standard-Aussehen aller Schritte: `height` (Standard `100%`), `colorLabel` (`#566eb1`), `fontSizeLabel` (`13px`), `colorValue` (`#3E6FFF`), `fontSizeValue` (`35px`), `backgroundColor` für Leiste, Werte und Linie (`#f7f8fc`), `borderColor` (`#e5e5e5`), `alignX` (`'left' | 'center' | 'right'`, Standard `center`), `stepWidth` als Mindestbreite je Schritt, `gapY` zwischen Titel, Wert und Untertitel, `stepRadius` für den Wert und `connectionLine` mit `show` (Standard `true`) und `height` (Standard `3px`).

Typ: `ArcWidgetStepsSettings`.

### steps

Schritte in Anzeigereihenfolge: `title`, `value`, `subtitle` als reiner Text, `clickable`, eine feste `width` sowie `colorLabel`, `fontSizeLabel`, `colorValue`, `fontSizeValue` und `backgroundColor` je Schritt, die `settings` überschreiben.

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.

- `title`, `value` und `subtitle` werden als reiner Text angezeigt; JSX-Elemente und HTML werden nicht gerendert.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: steps -->
```typescript
export interface ArcWidgetStepsConnectionLine {
	show?: boolean;
	height?: string;
}

export interface ArcWidgetStepsSettings {
	height?: string;
	colorLabel?: string;
	fontSizeLabel?: string;
	colorValue?: string;
	fontSizeValue?: string;
	backgroundColor?: string;
	borderColor?: string;
	alignX?: 'left' | 'center' | 'right';
	stepWidth?: string;
	gapY?: string;
	stepRadius?: string;
	connectionLine?: ArcWidgetStepsConnectionLine;
}

export interface ArcWidgetStepsStep {
	title?: string | number;
	value?: string | number;
	subtitle?: string | number;
	colorLabel?: string;
	fontSizeLabel?: string;
	colorValue?: string;
	fontSizeValue?: string;
	backgroundColor?: string;
	width?: string;
	clickable?: boolean;
}

export interface ArcWidgetStepsData {
	settings?: ArcWidgetStepsSettings;
	steps?: ArcWidgetStepsStep[];
}

export interface ArcWidgetStepsProps extends ArcReactWidgetProps<ArcWidgetStepsData> {
	onClick?: (event: MouseEvent, 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)
<!-- /host -->

<!-- host:ninox -->
# 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.

<iframe src="https://www.youtube.com/embed/qoMVaVCJ1Sw?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>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.**

![](https://framerusercontent.com/images/i14A175WOPvdKLDT7G7rK5XQlmE.png)

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

![](https://framerusercontent.com/images/IprIm5AORs6cO1ATQc2gvMZtdc.png)

### 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: [...]
}
```

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`title`

</td><td>`text`

</td><td>Titel oberhalb des Kreises

</td></tr><tr><td>`value`

</td><td>`text`/`number`

</td><td>Zentrale Anzeige im Kreis

</td></tr><tr><td>`subtitle`

</td><td>`text`

</td><td>Text unterhalb des Kreises

</td></tr><tr><td>`width`

</td><td>`text`

</td><td>Individuelle Breite des Steps

</td></tr><tr><td>`colorLabel`

</td><td>`text`

</td><td>Textfarbe für `title` und `subtitle`

</td></tr><tr><td>`fontSizeLabel`

</td><td>`text`

</td><td>Schriftgröße für `title` und `subtitle`

</td></tr><tr><td>`colorValue`

</td><td>`text`

</td><td>Textfarbe des zentralen Werts

</td></tr><tr><td>`fontSizeValue`

</td><td>`text`

</td><td>Schriftgröße des Werts

</td></tr><tr><td>`backgroundColor`

</td><td>`text`

</td><td>Hintergrundfarbe des Kreises und der Verbindungslinien

</td></tr><tr><td>`borderColor`

</td><td>`text`

</td><td>Farbe der Step-Trennlinie

</td></tr><tr><td>`actions[]`

</td><td>`array`

</td><td>Aktionen, die beim Klick ausgelöst werden können (siehe unten)

</td></tr></tbody></table></figure>💡 **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:
<!-- /host -->

<!-- host:vue -->
# 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.

<iframe src="https://www.youtube.com/embed/qoMVaVCJ1Sw?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>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.**

![](https://framerusercontent.com/images/i14A175WOPvdKLDT7G7rK5XQlmE.png)

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

![](https://framerusercontent.com/images/IprIm5AORs6cO1ATQc2gvMZtdc.png)

### 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: [...]
}
```

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`title`

</td><td>`text`

</td><td>Titel oberhalb des Kreises

</td></tr><tr><td>`value`

</td><td>`text`/`number`

</td><td>Zentrale Anzeige im Kreis

</td></tr><tr><td>`subtitle`

</td><td>`text`

</td><td>Text unterhalb des Kreises

</td></tr><tr><td>`width`

</td><td>`text`

</td><td>Individuelle Breite des Steps

</td></tr><tr><td>`colorLabel`

</td><td>`text`

</td><td>Textfarbe für `title` und `subtitle`

</td></tr><tr><td>`fontSizeLabel`

</td><td>`text`

</td><td>Schriftgröße für `title` und `subtitle`

</td></tr><tr><td>`colorValue`

</td><td>`text`

</td><td>Textfarbe des zentralen Werts

</td></tr><tr><td>`fontSizeValue`

</td><td>`text`

</td><td>Schriftgröße des Werts

</td></tr><tr><td>`backgroundColor`

</td><td>`text`

</td><td>Hintergrundfarbe des Kreises und der Verbindungslinien

</td></tr><tr><td>`borderColor`

</td><td>`text`

</td><td>Farbe der Step-Trennlinie

</td></tr><tr><td>`actions[]`

</td><td>`array`

</td><td>Aktionen, die beim Klick ausgelöst werden können (siehe unten)

</td></tr></tbody></table></figure>💡 **Tipp: **Du musst nicht alle Felder angeben. Jeder Step übernimmt automatisch die Werte aus `settings`, wenn keine eigenen Angaben gemacht werden.
<!-- /host -->


---

# Custom Table

Source: https://www.arc-rider.com/docs/widgets/custom-table


<!-- host:react -->
# Table in React

Listen mit sortierbaren Spalten, Zeilenaktionen und eingebetteten Komponenten. Geeignet für Aufträge, Inventar und Auswahllisten.

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

<!-- react-example: table-00-defaults.tsx -->
```tsx
import { ArcWidgetTable } from '@arcrider/arcwidgets-react';

const columns = [
  { title: 'Status', width: '100px' },
  { title: 'Appointment', width: '120px' },
  { title: 'Patient', width: 'fraction' },
  { title: 'Date of birth', width: '140px' },
];
const appointments = [
  ['Planned', '14.06.2026', 'Albert Bear', '01.01.1980'],
  ['-', '15.06.2026', 'Maya Bee', '02.02.1990'],
  ['Completed', '16.06.2026', 'Carla Summer', '03.03.1985'],
  ['Scheduled', '17.06.2026', 'Dieter Fox', '04.04.1975'],
  ['Open', '18.06.2026', 'Eva Green', '05.05.1992'],
];
const rows = appointments.map((values, index) => ({
  id: String(index + 1),
  columns: columns.map((column, i) => ({
    value: values[i],
    width: column.width,
  })),
}));

export default function Example() {
  return (
    <ArcWidgetTable
      data={{
        height: '400px',
        rowHoverAction: { hoverActive: true },
        header: { columns },
        table: rows,
        scrollBar: { showScrollBar: false },
        footer: { showFooter: true, rightSideContent: `Total: ${rows.length}` },
      }}
    />
  );
}
```

## Features ausprobieren

### Sortierung, Unterzeilen, JSX-Zellen und leerer Zustand

Sortiere über die Spaltenüberschriften, klappe Unterzeilen auf und wechsle zur leeren Liste. Die Statuszellen sind echte Badge-Komponenten.

<!-- react-example: table-07-look_dark.tsx -->
```tsx
import { ArcWidgetTable } from '@arcrider/arcwidgets-react';

const columns = [
  { title: 'Status', width: '100px' },
  { title: 'Appointment', width: '120px' },
  { title: 'Patient', width: 'fraction' },
  { title: 'Date of birth', width: '140px' },
];
const appointments = [
  ['Planned', '14.06.2026', 'Albert Bear', '01.01.1980'],
  ['-', '15.06.2026', 'Maya Bee', '02.02.1990'],
  ['Completed', '16.06.2026', 'Carla Summer', '03.03.1985'],
  ['Scheduled', '17.06.2026', 'Dieter Fox', '04.04.1975'],
  ['Open', '18.06.2026', 'Eva Green', '05.05.1992'],
];
const rows = appointments.map((values, index) => ({
  id: String(index + 1),
  columns: columns.map((column, i) => ({
    value: values[i],
    width: column.width,
  })),
}));

export default function Example() {
  return (
    <ArcWidgetTable
      data={{
        height: '400px',
        styles: {
          backgroundColor: '#2a2822',
          fontColor: '#f5f0e6',
          borderRadius: '12px',
          borderColor: '#3f3c34',
          borders: { outer: true, rows: { color: '#3a372f' }, columns: false },
        },
        rowHoverAction: {
          hoverActive: true,
          backgroundColor: '#35322a',
          fontColor: '#f5f0e6',
        },
        header: { columns, fontColor: '#f5f0e6', backgroundColor: '#1c1b16' },
        table: rows,
        scrollBar: { showScrollBar: false },
        footer: { showFooter: true, rightSideContent: `Total: ${rows.length}` },
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Maus-Event und Zellenposition. Benötigt `clickable: true` an Zeile oder Zelle.

```typescript
onCellClick?: (event: MouseEvent, payload: ArcWidgetTableCellPayload) => void;
```

### onCellHoverEnter

Position der betretenen Zelle; benötigt `hover_enterable: true` an der Zelle.

```typescript
onCellHoverEnter?: (payload: ArcWidgetTableCellPayload) => void;
```

### onCellHoverLeave

Position der verlassenen Zelle; benötigt `hover_leaveable: true` an der Zelle.

```typescript
onCellHoverLeave?: (payload: ArcWidgetTableCellPayload) => void;
```

### onFooterActionClick

Maus-Event des Aktionsbuttons im Footer; benötigt `footer.showActionButton: true`.

```typescript
onFooterActionClick?: (event: MouseEvent) => 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"`, oder `"auto"`, damit es mit den Zeilen wächst (mit `maxHeight` kombinieren, um zu scrollen). Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.

Typ: `string`.

### minHeight

Untere Höhengrenze.

Typ: `string`.

### width

CSS-Breite der Tabelle. Standard ist `100%`.

Typ: `string`.

### maxHeight

Obere Höhengrenze. Mit `height: "auto"` scrollt der Tabellenkörper darüber hinaus.

Typ: `string`.

### groupedBy

`field` der Zellen, nach dem Zeilen gruppiert werden; weglassen für flache Tabellen. Wird ignoriert, wenn Zeilen verschachtelte `items` haben.

Typ: `string`.

### groupsCollapsed

Anfangszustand der Gruppen. Standardmäßig starten Gruppen eingeklappt; mit `false` starten sie aufgeklappt. Die Wahl pro Gruppe wird gemerkt.

Typ: `boolean`.

### collapsible

Auf- und Zuklappen für Zeilen mit verschachtelten `items`: Spalte des Umschalters, Einrückung und optionale eigene Icons.

Typ: `ArcWidgetTableCollapsible`.

### rowHoverAction

Zeilenhervorhebung beim Überfahren einer Zeile. Standardmäßig aus; mit `hoverActive: true` einschalten.

Typ: `ArcWidgetTableHoverAction`.

### actions

Hover-Einstellungen für alle Zeilen, z. B. `[{ type: 'hover', enabled: false }]`. Zeilen und Zellen können sie mit eigenen `actions` überschreiben.

Typ: `ArcWidgetAction[]`.

### header

Spaltenüberschriften, Breiten, Ausrichtung, fixierte Spalten 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. Der eingebaute Text ist deutsch; setze für andere Sprachen `title` oder `value`.

Typ: `ArcWidgetTableEmpty`.

### scrollBar

Aussehen der Scrollbalken. Der horizontale Balken erscheint automatisch, wenn die Spalten breiter als die Tabelle sind; `showScrollBar: true` zeigt zusätzlich den vertikalen.

Typ: `ArcWidgetTableScrollBar`.

### table

Datenzeilen mit `columns`; optionale Unterzeilen stehen in `items`.

Typ: `ArcWidgetTableRow[]`.

### footerColumns

Summenzeile zwischen Tabellenkörper und Footer, z. B. für Gesamtwerte. Sie nutzt das Spaltenraster des Headers; ohne eigene `columns` zeigt sie den `footer`-Text jeder Header-Spalte.

Typ: `ArcWidgetTableFooterColumns`.

### footer

Inhalte und Sichtbarkeit des Tabellenfußes.

Typ: `ArcWidgetTableFooter`.

### styles

Fläche und Linien der Tabelle: `backgroundColor`, `fontColor`, `fontSize`, `borderColor`, `borderSize`, `borderRadius` und `borders` für Außenrahmen, Zeilen- und Spaltenlinien. Weitere CSS-Schlüssel werden auf das Widget-Element angewendet.

Typ: `ArcWidgetTableStyles | string`.

## Verhalten und Grenzen

- Jede Spalte braucht eine Breite. Am besten mindestens einmal `width: "fraction"` oder `"auto"`; Header und Zellen müssen dieselbe Spaltenreihenfolge haben. Sind alle Spalten fix und zusammen schmaler als die Tabelle, wächst die letzte Spalte und füllt den Rest.

- Setze `clickable: true` auf der Zeile oder Zelle, damit `onCellClick` ausgelöst wird. `row_index` zeigt auf `data.table` und bleibt von der Sortierung unberührt; bei verschachtelten `items` ist er `null`, dort nutzt du `flat_index`.

- Spalten richtest du mit `alignX: 'left' | 'center' | 'right'` an der Header-Spalte und ihren Zellen aus.

- Bei JSX-Zellinhalten braucht Sortierung einen skalaren `sort.value`. Datumsspalten sortieren mit `new Date(value)`; lokalisierte Strings wie `"14.06.2026"` brauchen daher einen `sort.value` mit Zeitstempel oder ISO-Datum.

- 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: table -->
```typescript
export interface ArcWidgetTableCellPayload {
	row_index: number | null;
	col_index: number;
	flat_index: number | null;
	group_value: string | null;
}

export interface ArcWidgetTableSort {
	enabled?: boolean;
	type?: 'text' | 'number' | 'date';
	value?: string | number;
}

export interface ArcWidgetTableSortIcons {
	color?: string;
	activeColor?: string;
	hoverColor?: string;
}

export interface ArcWidgetTableHeaderColumn {
	title?: ArcWidgetSlot;
	width?: 'fraction' | 'auto' | (string & {});
	minWidth?: string;
	alignX?: 'left' | 'center' | 'right';
	fixed?: 'left' | 'right';
	sort?: ArcWidgetTableSort;
	fontColor?: string;
	backgroundColor?: string;
	styles?: ArcWidgetCssStyles | string;
	footer?: string;
}

export interface ArcWidgetTableHeader {
	showHeader?: boolean;
	columns?: ArcWidgetTableHeaderColumn[];
	height?: 'auto' | (string & {});
	fontSize?: string;
	fontColor?: string;
	backgroundColor?: string;
	styles?: ArcWidgetCssStyles | string;
	sortIcons?: ArcWidgetTableSortIcons;
}

export interface ArcWidgetTableColumn {
	value?: ArcWidgetSlot;
	field?: string;
	title?: ArcWidgetSlot;
	width?: 'fraction' | 'auto' | (string & {});
	minWidth?: string;
	alignX?: 'left' | 'center' | 'right';
	fixed?: 'left' | 'right';
	fontColor?: string;
	backgroundColor?: string;
	paddingX?: string;
	paddingY?: string;
	styles?: ArcWidgetCssStyles | string;
	actions?: ArcWidgetAction[];
	clickable?: boolean;
	hover_enterable?: boolean;
	hover_leaveable?: boolean;
	sort?: ArcWidgetTableSort;
	span?: number;
	groupValue?: ArcWidgetSlot;
	groupByValue?: string | number;
	groupExpandAction?: boolean;
}

export interface ArcWidgetTableGroupRowSettings {
	height?: string;
}

export interface ArcWidgetTableHoverAction {
	hoverActive?: boolean;
	backgroundColor?: string;
	fontColor?: string;
}

export interface ArcWidgetTableRow {
	id?: string | number;
	columns?: ArcWidgetTableColumn[];
	items?: ArcWidgetTableRow[];
	clickable?: boolean;
	rowColor?: string;
	fontColor?: string;
	rowHeight?: string;
	rowPaddingY?: string;
	styles?: ArcWidgetCssStyles | string;
	actions?: ArcWidgetAction[];
	rowHoverAction?: ArcWidgetTableHoverAction;
	groupRowColor?: string;
	groupRowSettings?: ArcWidgetTableGroupRowSettings;
}

export interface ArcWidgetTableEmpty {
	title?: string;
	value?: ArcWidgetSlot;
	backgroundColor?: string;
}

export interface ArcWidgetTableFooter {
	showFooter?: boolean;
	height?: 'auto' | (string & {});
	backgroundColor?: string;
	showActionButton?: boolean;
	actionButtonTitle?: string;
	leftSideContent?: ArcWidgetSlot;
	rightSideContent?: ArcWidgetSlot;
	styles?: ArcWidgetCssStyles | string;
}

export interface ArcWidgetTableFooterColumn {
	footer?: string;
	alignX?: 'left' | 'center' | 'right';
	fixed?: 'left' | 'right';
	minWidth?: string;
	fontColor?: string;
	backgroundColor?: string;
}

export interface ArcWidgetTableFooterColumns {
	show?: boolean;
	backgroundColor?: string;
	columns?: ArcWidgetTableFooterColumn[];
}

export interface ArcWidgetTableScrollBarHandle {
	backgroundColor?: string;
	borderRadius?: string;
}

export interface ArcWidgetTableScrollBar {
	showScrollBar?: boolean;
	height?: string;
	backgroundColor?: string;
	handle?: ArcWidgetTableScrollBarHandle;
}

export interface ArcWidgetTableBorderLineStyle {
	enabled?: boolean;
	color?: string;
	width?: string;
}

export type ArcWidgetTableBorderLine = boolean | ArcWidgetTableBorderLineStyle;

export interface ArcWidgetTableBorders {
	color?: string;
	width?: string;
	outer?: ArcWidgetTableBorderLine;
	columns?: ArcWidgetTableBorderLine;
	rows?: ArcWidgetTableBorderLine;
}

export interface ArcWidgetTableStyles extends ArcWidgetCssStyles {
	backgroundColor?: string;
	fontColor?: string;
	fontSize?: string;
	borderColor?: string;
	borderSize?: string;
	borderRadius?: string;
	borders?: ArcWidgetTableBorders;
}

export interface ArcWidgetTableCollapsible {
	enabled?: boolean;
	defaultCollapsed?: boolean;
	expandColumn?: number;
	indentColumn?: number;
	indentSize?: string;
	iconSize?: string;
	iconExpand?: ArcWidgetSlot;
	iconCollapse?: ArcWidgetSlot;
}

export interface ArcWidgetTableData {
	table?: ArcWidgetTableRow[];
	header?: ArcWidgetTableHeader;
	height?: 'auto' | (string & {});
	minHeight?: string;
	maxHeight?: string;
	width?: string;
	groupedBy?: string;
	groupsCollapsed?: boolean;
	collapsible?: ArcWidgetTableCollapsible;
	rowHoverAction?: ArcWidgetTableHoverAction;
	actions?: ArcWidgetAction[];
	emptyTable?: ArcWidgetTableEmpty;
	scrollBar?: ArcWidgetTableScrollBar;
	footerColumns?: ArcWidgetTableFooterColumns;
	footer?: ArcWidgetTableFooter;
	styles?: ArcWidgetTableStyles | string;
}

export interface ArcWidgetTableProps extends ArcReactWidgetProps<ArcWidgetTableData> {
	onCellClick?: (event: MouseEvent, payload: ArcWidgetTableCellPayload) => void;
	onCellHoverEnter?: (payload: ArcWidgetTableCellPayload) => void;
	onCellHoverLeave?: (payload: ArcWidgetTableCellPayload) => void;
	onFooterActionClick?: (event: MouseEvent) => 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)
<!-- /host -->

<!-- host:ninox -->
# Custom Table

## AI Defaults (read first)

- **Column widths**: Every column MUST have explicit `width`. Prefer at least one `width: "fraction"` or `"auto"`. If every column is a fixed length and the tracks are narrower than the table, the last column grows to fill the leftover space.
- **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).

<iframe src="https://www.youtube.com/embed/gnP9o5NCefk?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1&loop=1&playlist=gnP9o5NCefk" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## Beispiel:

![](https://framerusercontent.com/images/LW07tfdMxAVkiyhTZ9GOJlmHFws.png)

## 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)
```

<iframe src="https://www.youtube.com/embed/wuHZMD3Ym5Q?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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.
        },
```

![](https://framerusercontent.com/images/bAxu68gh9ycCRLInmZwR463qpeI.png)

### 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.
- `**height**`: Höhe des Footers (z. B. `"48px"`). Ohne Angabe gilt die Header-Höhe, Standard `36px`.
- `**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:

![](https://framerusercontent.com/images/juhFlR4IcYzPbEQW10jXQF8x2Ic.png)

## 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`: alle Elternzeilen starten zugeklappt, auch solche, die später dazukommen. Auf- und Zuklappen bleibt gespeichert |
| `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` | Optionaler verschachtelter Widget-Descriptor (z. B. `arcCustomIcon`), solange die Zeile **eingeklappt** ist, ein Klick klappt also auf — ersetzt das Standard-Caret |
| `iconCollapse` | Optionaler verschachtelter Widget-Descriptor, solange die Zeile **aufgeklappt** ist, ein Klick klappt also zu — ersetzt das Standard-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). Sind alle Spalten fix und zusammen schmaler als die Tabelle, übernimmt die letzte Spalte den Rest (wie `"auto"`).
- `**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
```

<iframe src="https://www.youtube.com/embed/Ez-IlPbx7kI?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=0&mute=1" data-thumbnail="High Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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
```

![](https://framerusercontent.com/images/yp7bARVTzbVbdb75ZV2DK0mkA.png)

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

![](https://framerusercontent.com/images/pvAEOaUFtbYHMPzHd4v82XWP3nk.png)


```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: "<h1>",
                        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

![](https://framerusercontent.com/images/OUceOtboxPQac3AJ3N3DEu9yas.png)


```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)
```
<!-- /host -->

<!-- host:vue -->
# Custom Table

## AI Defaults (read first)

- **Column widths**: Every column MUST have explicit `width`. Prefer at least one `width: "fraction"` or `"auto"`. If every column is a fixed length and the tracks are narrower than the table, the last column grows to fill the leftover space.
- **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).

<iframe src="https://www.youtube.com/embed/gnP9o5NCefk?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1&loop=1&playlist=gnP9o5NCefk" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## Beispiel:

![](https://framerusercontent.com/images/LW07tfdMxAVkiyhTZ9GOJlmHFws.png)

## 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)
```

<iframe src="https://www.youtube.com/embed/wuHZMD3Ym5Q?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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.
        },
```

![](https://framerusercontent.com/images/bAxu68gh9ycCRLInmZwR463qpeI.png)

### 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.
- `**height**`: Höhe des Footers (z. B. `"48px"`). Ohne Angabe gilt die Header-Höhe, Standard `36px`.
- `**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:

![](https://framerusercontent.com/images/juhFlR4IcYzPbEQW10jXQF8x2Ic.png)

## 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`: alle Elternzeilen starten zugeklappt, auch solche, die später dazukommen. Auf- und Zuklappen bleibt gespeichert |
| `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` | Optionaler verschachtelter Widget-Descriptor (z. B. `arcCustomIcon`), solange die Zeile **eingeklappt** ist, ein Klick klappt also auf — ersetzt das Standard-Caret |
| `iconCollapse` | Optionaler verschachtelter Widget-Descriptor, solange die Zeile **aufgeklappt** ist, ein Klick klappt also zu — ersetzt das Standard-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). Sind alle Spalten fix und zusammen schmaler als die Tabelle, übernimmt die letzte Spalte den Rest (wie `"auto"`).
- `**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
```

<iframe src="https://www.youtube.com/embed/Ez-IlPbx7kI?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=0&mute=1" data-thumbnail="High Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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
```

![](https://framerusercontent.com/images/yp7bARVTzbVbdb75ZV2DK0mkA.png)

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

![](https://framerusercontent.com/images/pvAEOaUFtbYHMPzHd4v82XWP3nk.png)


```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: "<h1>",
                        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

![](https://framerusercontent.com/images/OUceOtboxPQac3AJ3N3DEu9yas.png)


```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
<ArcWidgetTable id="orders" :data="tableData" @action="handleAction" />
```
<!-- /host -->


---

# Custom Upload

Source: https://www.arc-rider.com/docs/widgets/custom-upload


<!-- host:react -->
# 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

<!-- react-example: upload-04-standard.tsx -->
```tsx
import { ArcWidgetUpload } from '@arcrider/arcwidgets-react';

export default function Example() {
  return (
    <ArcWidgetUpload
      data={{
        multiupload: true,
        container: { label: 'Upload files', width: '100%', height: '150px' },
      }}
    />
  );
}
```

## Features ausprobieren

### Mehrfachauswahl und Bildkonvertierung

Wähle eigene Bilder und vergleiche die Qualitätseinstellungen. Die Dateien werden ausschließlich lokal im Browser verarbeitet.

<!-- react-example: upload-01-capture.tsx -->
```tsx
import { ArcWidgetUpload } from '@arcrider/arcwidgets-react';

export default function Example() {
  return (
    <ArcWidgetUpload
      data={{
        capture: true,
        multiupload: false,
        container: { label: 'Open camera' },
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Wird je aufbereiteter Datei aufgerufen, mit `name`, `src` (Data-URL), Bildmaßen und `original`. Die nächste Datei wartet, bis ein zurückgegebenes Promise abgeschlossen ist.

```typescript
onUpload?: (payload: ArcWidgetUploadPayload) => void | Promise<void>;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### container

Pflichtfeld. Inhalt der Upload-Fläche: `label` unter dem Standard-Icon oder ein eigener `value`, dazu `width`, `height`, `paddingX` und `paddingY`.

Typ: `ArcWidgetUploadContainer`.

### multiupload

Erlaubt die Auswahl mehrerer Dateien. Standard: `false`.

Typ: `boolean`.

### capture

Öffnet auf unterstützten Geräten die Rückkamera und akzeptiert nur Bilder. Standard: `false`.

Typ: `boolean`.

### allowedFileTypes

Dateitypen im Dateidialog: Endungen wie `"pdf"` oder `".docx"`, MIME-Typen wie `"image/*"` oder `'all'`. Standard: Bilder, PDF, XML, CSV und Excel-Dateien.

Typ: `string[] | 'all'`.

### image

Maximale Größe, Ausgabeformat (`jpeg`, `webp`, `original`) und Qualität (Standard `0.8`) für Bilder.

Typ: `ArcWidgetUploadImage`.

### clipboard

Nimmt mit Strg/Cmd+V eingefügte Dateien an. Ein Objekt legt Text und Ecke des Tooltips fest.

Typ: `boolean | ArcWidgetUploadClipboard`.

### drag

Dateien per Drag & Drop auswählen. Standardmäßig aktiv, wenn `container.value` nicht gesetzt ist; mit `targetId` wird ein anderes Element, z. B. eine Tabellenzeile oder ein Layout-Block mit dieser `blockId`, zur Ablagefläche.

Typ: `boolean | ArcWidgetUploadDrag`.

### showLoadingPopup

Fortschrittsdialog mit Abbrechen-Button während der Verarbeitung. Standard: `false`.

Typ: `boolean`.

### logs

Schreibt Kodierungsergebnisse in die Konsole und zeigt eine Vorschau des zuletzt kodierten Bildes. Standard: `false`.

Typ: `boolean | { enabled?: boolean }`.

### lang

Sprache der eingebauten Texte. Standard: `en`.

Typ: `'en' | 'de'`.

## Verhalten und Grenzen

- `onUpload` wird pro Datei aufgerufen und erhält `name`, `src`, `original` 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: upload -->
```typescript
export interface ArcWidgetUploadImage {
	width?: number;
	height?: number;
	format?: 'jpeg' | 'webp' | 'original';
	quality?: number;
}

export interface ArcWidgetUploadDrag {
	enabled?: boolean;
	label?: string;
	target?: 'area' | 'first-child' | 'layout';
	targetId?: string;
}

export interface ArcWidgetUploadClipboardTooltip {
	value?: string;
	position?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center';
}

export interface ArcWidgetUploadClipboard {
	tooltip?: string | ArcWidgetUploadClipboardTooltip;
}

export interface ArcWidgetUploadContainer {
	label?: string;
	value?: ArcWidgetSlot;
	width?: string;
	height?: string;
	paddingX?: string;
	paddingY?: string;
}

export interface ArcWidgetUploadData {
	container: ArcWidgetUploadContainer;
	multiupload?: boolean;
	capture?: boolean;
	allowedFileTypes?: string[] | 'all';
	image?: ArcWidgetUploadImage;
	clipboard?: boolean | ArcWidgetUploadClipboard;
	drag?: boolean | ArcWidgetUploadDrag;
	showLoadingPopup?: boolean;
	logs?: boolean | { enabled?: boolean };
	lang?: 'en' | 'de';
}

export interface ArcWidgetUploadPayload {
	name: string;
	src: string;
	width?: number;
	height?: number;
}

export interface ArcWidgetUploadProps extends ArcReactWidgetProps<ArcWidgetUploadData> {
	onUpload?: (payload: ArcWidgetUploadPayload) => void | Promise<void>;
}
```

## 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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? }`. Ninox handler builds `update` / `create` / `popup` from `ui.data.image.*`. 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

<iframe src="https://www.youtube.com/embed/wGEOv0xiAKY?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>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.

![](https://framerusercontent.com/images/tfmYk7LEFF3TRtIAdgEuiSIf1hs.png)

## 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")
        },
        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 (oder eine Layout-`blockId`) 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**

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`label`

</td><td>`text`

</td><td>Beschriftung (Text) im Upload-Feld. Wird in der Mitte angezeigt. Wird unter dem Icon angezeigt.

</td></tr><tr><td>`value`

</td><td>`widget` `text`

</td><td>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.

</td></tr><tr><td>`height`

</td><td>`text`

</td><td>Höhe des Upload-Feldes, z. B. `"80px"` oder `"100%"`.

</td></tr><tr><td>`width`

</td><td>`text`

</td><td>Breite des Upload-Feldes, z. B. `"100%"`, `"300px"` oder `"auto"`.

</td></tr><tr><td>`icon`

</td><td>`widget`

</td><td>Mit `[arcCustomIcon](https://www.arc-rider.de/documentation/custom-icon)` kann ein individuelles Icon bestimmt werden.

</td></tr></tbody></table></figure>💡 **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.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`tableId`

</td><td>`text`

</td><td>Ziel-Tabelle, in der das Bild als Datensatz gespeichert wird.

</td></tr><tr><td>`fieldId`

</td><td>`text`

</td><td>Feld-ID des Textfelds, in das der Base64-Bildinhalt geschrieben wird.

</td></tr><tr><td>`widthFieldId`

</td><td>`text`

</td><td>*(optional)* Feld-ID für die gespeicherte Bildbreite (in Pixeln). Erstelle dafür ein Ninox-Zahlenfeld.

</td></tr><tr><td>`heightFieldId`

</td><td>`text`

</td><td>*(optional)* Feld-ID für die gespeicherte Bildhöhe (in Pixeln). Erstelle dafür ein Ninox-Zahlenfeld.

</td></tr><tr><td>`width` / `height`

</td><td>`text`

</td><td>*(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.

</td></tr><tr><td>`format`

</td><td>`text`

</td><td>*(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`).

</td></tr><tr><td>`quality`

</td><td>`number`

</td><td>*(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"`.

</td></tr></tbody></table></figure>

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.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`tableId`

</td><td>`text`

</td><td>Ziel-Tabelle, in der der Datensatz gespeichert wird

</td></tr><tr><td>`fieldId`

</td><td>`text`

</td><td>Feld-ID, in das der Dateiname geschrieben wird

</td></tr></tbody></table></figure>💡 **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:

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`fieldId`

</td><td>`text`

</td><td>Das Feld im neuen Datensatz, das gesetzt werden soll

</td></tr><tr><td>`value`

</td><td>`any`

</td><td>Der Wert, der in das Feld geschrieben wird

</td></tr></tbody></table></figure>
```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.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`recordId`

</td><td>`text`

</td><td>Der ID-Wert des bestehenden Datensatzes, in dem verlinkt werden soll

</td></tr><tr><td>`fieldId`

</td><td>`text`

</td><td>Das Referenzfeld, das mit dem neuen Upload-Datensatz gefüllt werden soll

</td></tr></tbody></table></figure>## ✅ 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 und Automatisierungen.

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.
<!-- /host -->


---

# Badges

Source: https://www.arc-rider.com/docs/mini-widgets/badges


<!-- host:react -->
# 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

<!-- react-example: badge-01-status.tsx -->
```tsx
import { ArcWidgetBadge, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

const svg = (d: string) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 256 256"
    style={{ width: '1em', height: '1em', fill: 'currentColor' }}
  >
    <path d={d} />
  </svg>
);

const iconCheck = svg(
  'M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l-56-56a8,8,0,0,1,11.32-11.32L96,188.69,218.34,66.34a8,8,0,0,1,11.32,11.32Z',
);
const iconClock = svg(
  'M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm0,192a88,88,0,1,1,88-88A88.1,88.1,0,0,1,128,216Zm64-88a8,8,0,0,1-8,8H128a8,8,0,0,1-8-8V72a8,8,0,0,1,16,0v48h48A8,8,0,0,1,192,128Z',
);
const iconWarning = svg(
  'M236.8,188.09,149.35,36.22a24.76,24.76,0,0,0-42.7,0L19.2,188.09a23.51,23.51,0,0,0,0,23.72A24.35,24.35,0,0,0,40.55,224h174.9a24.35,24.35,0,0,0,21.33-12.19A23.51,23.51,0,0,0,236.8,188.09ZM120,104a8,8,0,0,1,16,0v40a8,8,0,0,1-16,0Zm8,88a12,12,0,1,1,12-12A12,12,0,0,1,128,192Z',
);
const iconX = svg(
  'M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z',
);
const iconDot = svg('M128,48a80,80,0,1,0,80,80A80,80,0,0,0,128,48Z');

// One `singleColor` derives text, icon, background and border.
const statuses = [
  { value: 'Active', icon: iconCheck, singleColor: '#16A34A' },
  { value: 'Online', icon: iconDot, singleColor: '#0EA5E9' },
  { value: 'In progress', icon: iconClock, singleColor: '#D97706' },
  { value: 'Warning', icon: iconWarning, singleColor: '#CA8A04' },
  { value: 'Error', icon: iconX, singleColor: '#DC2626' },
  { value: 'Inactive', singleColor: '#64748B' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: statuses.map((status) => ({
          width: 'auto',
          value: (
            <ArcWidgetBadge
              data={{ iconPosition: 'left', fontWeight: '600', ...status }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Features ausprobieren

Jedes Beispiel setzt nur die Werte, die die Variante ausmachen.

### Zähler

Eine kleine rote Pille für ungelesene Zähler. `borderRadius: '999px'` rundet die Enden vollständig ab.

<!-- react-example: badge-02-count.tsx -->
```tsx
import { ArcWidgetBadge, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

const counts = ['3', '12', '99+'];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: counts.map((count) => ({
          width: 'auto',
          value: (
            <ArcWidgetBadge
              data={{
                value: count,
                backgroundColor: '#EF4444',
                borderColor: '#EF4444',
                fontColor: '#FFFFFF',
                fontWeight: '700',
                fontSize: '11px',
                borderRadius: '999px',
                paddingX: '7px',
                paddingY: '2px',
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

### Outline, Solid und Größe

Füllung, Rahmen, Text, Eckenradius und Innenabstand bestimmen den Look. Ein transparentes `backgroundColor` ergibt ein Outline-Badge.

<!-- react-example: badge-03-styles.tsx -->
```tsx
import { ArcWidgetBadge, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

const svg = (d: string) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 256 256"
    style={{ width: '1em', height: '1em', fill: 'currentColor' }}
  >
    <path d={d} />
  </svg>
);

const iconUser = svg(
  'M230.92,212c-15.23-26.33-38.7-45.21-66.09-54.16a72,72,0,1,0-73.66,0C63.78,166.78,40.31,185.66,25.08,212a8,8,0,1,0,13.85,8c18.84-32.56,52.14-52,89.07-52s70.23,19.44,89.07,52a8,8,0,1,0,13.85-8ZM72,96a56,56,0,1,1,56,56A56.06,56.06,0,0,1,72,96Z',
);
const iconBell = svg(
  'M221.8,175.94C216.25,166.38,208,139.33,208,104a80,80,0,1,0-160,0c0,35.34-8.26,62.38-13.81,71.94A16,16,0,0,0,48,200H88.81a40,40,0,0,0,78.38,0H208a16,16,0,0,0,13.8-24.06ZM128,216a24,24,0,0,1-23.72-20.5h47.44A24,24,0,0,1,128,216Z',
);
const iconStar = svg(
  'M239.2,97.29a16,16,0,0,0-13.81-11L166,81.17,142.72,25.81h0a15.95,15.95,0,0,0-29.44,0L90.07,81.17,30.61,86.32a16,16,0,0,0-9.11,28.06L66.61,153.8,53.09,212.34a16,16,0,0,0,23.84,17.34l51-31,51.11,31a16,16,0,0,0,23.84-17.34l-13.51-58.6,45.1-39.36A16,16,0,0,0,239.2,97.29Z',
);
const iconWarning = svg(
  'M236.8,188.09,149.35,36.22a24.76,24.76,0,0,0-42.7,0L19.2,188.09a23.51,23.51,0,0,0,0,23.72A24.35,24.35,0,0,0,40.55,224h174.9a24.35,24.35,0,0,0,21.33-12.19A23.51,23.51,0,0,0,236.8,188.09ZM120,104a8,8,0,0,1,16,0v40a8,8,0,0,1-16,0Zm8,88a12,12,0,1,1,12-12A12,12,0,0,1,128,192Z',
);

const styles = [
  {
    // Transparent fill, colored border and text.
    value: 'Outline',
    icon: iconUser,
    backgroundColor: 'transparent',
    borderColor: '#0EA5E9',
    fontColor: '#0EA5E9',
    iconColor: '#0EA5E9',
    fontWeight: '600',
  },
  {
    // Dark fill, white text.
    value: 'Solid',
    icon: iconBell,
    backgroundColor: '#1E293B',
    borderColor: '#1E293B',
    fontColor: '#FFFFFF',
    iconColor: '#FFFFFF',
    fontWeight: '600',
  },
  {
    // Fully rounded ends.
    value: 'Premium',
    singleColor: '#9333EA',
    fontWeight: '600',
    borderRadius: '999px',
    paddingX: '10px',
  },
  {
    // Small and tight, sharp corners.
    value: 'NEW',
    icon: iconStar,
    backgroundColor: '#EC4899',
    borderColor: '#EC4899',
    fontColor: '#FFFFFF',
    iconColor: '#FFFFFF',
    fontWeight: '700',
    fontSize: '10px',
    borderRadius: '4px',
    paddingX: '8px',
    paddingY: '3px',
  },
  {
    // Large: size, padding and radius grow together.
    value: 'Important',
    icon: iconWarning,
    singleColor: '#DC2626',
    fontWeight: '700',
    fontSize: '16px',
    borderRadius: '8px',
    paddingX: '14px',
    paddingY: '8px',
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: styles.map((style) => ({
          width: 'auto',
          value: <ArcWidgetBadge data={{ iconPosition: 'left', ...style }} />,
        })),
      }}
    />
  );
}
```

### Trend mit Pfeil

`iconPosition: 'right'` setzt den Pfeil hinter die Zahl.

<!-- react-example: badge-04-trend.tsx -->
```tsx
import { ArcWidgetBadge, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

const svg = (d: string) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 256 256"
    style={{ width: '1em', height: '1em', fill: 'currentColor' }}
  >
    <path d={d} />
  </svg>
);

const iconArrowUp = svg(
  'M205.66,117.66a8,8,0,0,1-11.32,0L136,59.31V216a8,8,0,0,1-16,0V59.31L61.66,117.66a8,8,0,0,1-11.32-11.32l72-72a8,8,0,0,1,11.32,0l72,72A8,8,0,0,1,205.66,117.66Z',
);
const iconArrowDown = svg(
  'M205.66,149.66l-72,72a8,8,0,0,1-11.32,0l-72-72a8,8,0,0,1,11.32-11.32L120,196.69V40a8,8,0,0,1,16,0V196.69l58.34-58.35a8,8,0,0,1,11.32,11.32Z',
);

// `iconPosition: 'right'` puts the arrow behind the number.
const trends = [
  { value: '+12%', icon: iconArrowUp, singleColor: '#16A34A' },
  { value: '-3.2%', icon: iconArrowDown, singleColor: '#DC2626' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: trends.map((trend) => ({
          width: 'auto',
          value: (
            <ArcWidgetBadge
              data={{ iconPosition: 'right', fontWeight: '700', ...trend }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Beschriftung des Badges; leere Werte zeigen keine Beschriftung.

Typ: `ArcWidgetSlot`.

### icon

Icon-Inhalt; erscheint nur, wenn `iconPosition` gesetzt ist.

Typ: `ArcWidgetSlot`.

### width

Breite des Badges; ohne Angabe richtet es sich nach dem Inhalt.

Typ: `string`.

### height

Höhe des Badges; `'auto'` behält die Inhaltshöhe.

Typ: `string`.

### iconPosition

Seite der Beschriftung, auf der das Icon sitzt; ohne Angabe bleibt das Icon ausgeblendet.

Typ: `'left' | 'right'`.

### iconSize

Breite und Höhe eines SVG-Icons; `'auto'` behält den Standard. Standard: `1.15em`.

Typ: `string`.

### iconColor

Füllfarbe eines SVG-Icons; fällt auf `singleColor` zurück.

Typ: `string`.

### fontColor

Schriftfarbe; fällt auf `singleColor` zurück. Standard: `#3e6fff`.

Typ: `string`.

### fontSize

Schriftgröße als CSS-Wert. Standard: `12px`.

Typ: `string`.

### fontWeight

Schriftstärke. Standard: `400`.

Typ: `string | number`.

### backgroundColor

Hintergrundfarbe; fällt auf `singleColor` mit 20 % Deckkraft zurück. Standard: `#dbe4ff`.

Typ: `string`.

### borderColor

Farbe des 1px-Rahmens; setze sie gleich `backgroundColor` für einen Look ohne Rahmen. Fällt auf `singleColor` mit 40 % Deckkraft zurück. Standard: `#3E6FFF`.

Typ: `string`.

### borderRadius

Abrundung der Ecken. Standard: `0.6em`.

Typ: `string`.

### singleColor

Sechsstellige Hex-Farbe, z. B. `'#16A34A'`, aus der Schrift-, Icon-, Hintergrund- und Rahmenfarbe abgeleitet werden, wenn diese fehlen.

Typ: `string`.

### paddingX

Innerer Abstand links und rechts. Standard: `0.3em`.

Typ: `string`.

### paddingY

Innerer Abstand oben und unten. Standard: `0.25em`.

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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: badge -->
```typescript
export interface ArcWidgetBadgeData {
	value?: ArcWidgetSlot;
	icon?: ArcWidgetSlot;
	iconPosition?: 'left' | 'right';
	width?: string;
	height?: string;
	iconSize?: string;
	iconColor?: string;
	fontColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
	borderColor?: string;
	borderRadius?: string;
	singleColor?: string;
	paddingX?: string;
	paddingY?: string;
}

export interface ArcWidgetBadgeProps extends ArcReactWidgetProps<ArcWidgetBadgeData> {}
```

## 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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

![](https://framerusercontent.com/images/GZ3ZMuhAEaLfjqObVHweqoidP6U.png)

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

<iframe src="https://www.youtube.com/embed/1fI1hv6ht5M?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1&loop=1&playlist=1fI1hv6ht5M" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>### 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.6em"
    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
})
```
<!-- /host -->


---

# Button

Source: https://www.arc-rider.com/docs/mini-widgets/buttons


<!-- host:react -->
# 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

Nur `title` ist gesetzt; alles andere ist Standard: schwarze Fläche, weiße fette Schrift, abgerundete Ecken und ein helleres Hover.

<!-- react-example: button-00-defaults.tsx -->
```tsx
import { ArcWidgetButton, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

export default function Example() {
  // Only required fields are set on the button; everything else is the widget default.
  // The Layout fills its surroundings and centers the button.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: [
          { width: 'auto', value: <ArcWidgetButton data={{ title: 'Save' }} /> },
        ],
      }}
    />
  );
}
```

## Features ausprobieren

Jedes Beispiel setzt nur die Werte, die die Variante ausmachen.

### Icon

`icon` nimmt jedes Element, zum Beispiel ein Phosphor-Icon, das die Schriftfarbe des Buttons übernimmt. `iconPosition: 'right'` setzt es hinter den Titel; `title: ''` ergibt einen reinen Icon-Button.

<!-- react-example: button-01-icon.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { DownloadSimpleIcon, PlusIcon } from '@phosphor-icons/react';

// Phosphor icons fill with `currentColor`, so they take the button text color.
const buttons: ArcWidgetButtonData[] = [
  {
    // Icon before the title (default `iconPosition`).
    title: 'New entry',
    icon: <PlusIcon size={16} />,
    gap: '6px',
  },
  {
    // Icon after the title.
    title: 'Export',
    icon: <DownloadSimpleIcon size={16} />,
    iconPosition: 'right',
    gap: '6px',
  },
  {
    // Icon only: empty title, `paddingX` equal to the default `paddingY` gives a square button.
    title: '',
    icon: <PlusIcon size={16} />,
    paddingX: '0.5em',
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map((data) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} />,
        })),
      }}
    />
  );
}
```

### Icon über dem Titel

`iconPosition: 'top'` stellt das Icon über den Titel, zum Beispiel in einer Werkzeugleiste. Eine gemeinsame `width` hält die Buttons gleich groß.

<!-- react-example: button-02-vertical.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { GearSixIcon, PlusIcon, UploadSimpleIcon } from '@phosphor-icons/react';

// `iconPosition: 'top'` stacks the icon above the title, e.g. for a toolbar.
// A shared `width` keeps the buttons the same size.
const vertical: ArcWidgetButtonData = {
  iconPosition: 'top',
  width: '96px',
  gap: '6px',
  paddingY: '12px',
  fontSize: '12px',
};

const buttons: ArcWidgetButtonData[] = [
  { ...vertical, title: 'New entry', icon: <PlusIcon size={20} /> },
  { ...vertical, title: 'Upload', icon: <UploadSimpleIcon size={20} /> },
  { ...vertical, title: 'Settings', icon: <GearSixIcon size={20} /> },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map((data) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} />,
        })),
      }}
    />
  );
}
```

### Benachrichtigungen

`showBadge` mit `badgeTitle` zeigt einen Zähler hinter dem Titel. `badgePosition: 'outside'` setzt ihn an die obere rechte Ecke.

<!-- react-example: button-03-notifications.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { BellIcon, TrayIcon } from '@phosphor-icons/react';

const buttons: ArcWidgetButtonData[] = [
  {
    // Inside: the badge follows the title.
    title: 'Inbox',
    icon: <TrayIcon size={16} />,
    gap: '6px',
    showBadge: true,
    badgeTitle: '3',
  },
  {
    // Outside: the badge sits on the top-right corner.
    title: 'Notifications',
    icon: <BellIcon size={16} />,
    gap: '6px',
    showBadge: true,
    badgeTitle: '12',
    badgePosition: 'outside',
  },
  {
    // Icon only with an outside badge.
    title: '',
    icon: <BellIcon size={16} />,
    paddingX: '0.5em',
    showBadge: true,
    badgeTitle: '5',
    badgePosition: 'outside',
  },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '24px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map((data) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} />,
        })),
      }}
    />
  );
}
```

### Präfix und Suffix

`prefix` sitzt am Anfang, `suffix` am Ende. `alignX` setzt den Titel in den Raum dazwischen: links, mittig oder rechts.

<!-- react-example: button-04-prefix_suffix.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { CaretRightIcon, UserIcon } from '@phosphor-icons/react';

// `prefix` sits on the start edge, `suffix` on the end edge.
// `alignX` places the title in the space between them.
const base: ArcWidgetButtonData = {
  width: '280px',
  gap: '8px',
  prefix: <UserIcon size={16} />,
  suffix: <CaretRightIcon size={16} />,
};

const buttons: ArcWidgetButtonData[] = [
  { ...base, title: 'Aligned left', alignX: 'left' },
  { ...base, title: 'Centered', alignX: 'center' },
  { ...base, title: 'Aligned right', alignX: 'right' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingY: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map((data) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} />,
        })),
      }}
    />
  );
}
```

### Ladezustand

Gibt `onClick` ein Promise zurück, zeigt ein Button mit `loading.show` den Indikator, bis das Promise abgeschlossen ist. Der Indikator übernimmt die Schriftfarbe und wächst mit der Schriftgröße. Mit `position` und `hide` ersetzt er das Präfix oder das Suffix; `hideTitle` ersetzt den Titel.

<!-- react-example: button-05-loading.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { CaretRightIcon, UserIcon } from '@phosphor-icons/react';

type Props = { onSave?: () => Promise<void> };

// Click a button: it shows the indicator until the `onClick` promise settles.
// Without own `loading.indicator` values the indicator takes the text color and scales with the font size.
const withSlots: ArcWidgetButtonData = {
  width: '240px',
  gap: '8px',
  prefix: <UserIcon size={16} />,
  suffix: <CaretRightIcon size={16} />,
};

const buttons: ArcWidgetButtonData[] = [
  {
    // Indicator next to the title.
    title: 'Save',
    loading: { show: true, minDuration: 1500 },
  },
  {
    // Replaces the prefix.
    ...withSlots,
    title: 'Replace prefix',
    loading: { show: true, minDuration: 1500, position: 'prefix', hide: { prefix: true } },
  },
  {
    // Replaces the title; prefix and suffix stay.
    ...withSlots,
    title: 'Replace title',
    loading: { show: true, minDuration: 1500, hideTitle: true },
  },
  {
    // Replaces the suffix.
    ...withSlots,
    title: 'Replace suffix',
    loading: { show: true, minDuration: 1500, position: 'suffix', hide: { suffix: true } },
  },
  {
    // A light button gets a dark indicator, because it follows `fontColor`.
    title: 'Sync',
    fontColor: '#18181B',
    backgroundColor: '#FFFFFF',
    borderColor: '#D4D4D8',
    loading: { show: true, minDuration: 1500 },
  },
];

const wait = () => new Promise<void>((resolve) => setTimeout(resolve, 1500));

export default function Example({ onSave = wait }: Props) {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingY: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map((data) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} onClick={onSave} />,
        })),
      }}
    />
  );
}
```

### Stile

Outline, Sekundär, Markenfarbe und eine destruktive Aktion. Eine eigene `backgroundColor` braucht keine `borderColor` und behält beim Hover ihre Farbe, solange `hoverActions` keine setzt. React hat keinen eingebauten Bestätigungsdialog; „Delete“ fragt per `window.confirm`, bevor `onDelete` aufgerufen wird.

<!-- react-example: button-06-styles.tsx -->
```tsx
import {
  ArcWidgetButton,
  ArcWidgetLayout,
  type ArcWidgetButtonData,
} from '@arcrider/arcwidgets-react';
import { TrashIcon } from '@phosphor-icons/react';

type Props = { onDelete?: () => void };

// A custom `backgroundColor` keeps its color on hover; set `hoverActions` for a hover color.
const outline: ArcWidgetButtonData = {
  title: 'Cancel',
  fontColor: '#18181B',
  backgroundColor: '#FFFFFF',
  borderColor: '#D4D4D8',
  hoverActions: { backgroundColor: '#F4F4F5' },
};

const secondary: ArcWidgetButtonData = {
  title: 'Duplicate',
  fontColor: '#18181B',
  backgroundColor: '#F4F4F5',
  hoverActions: { backgroundColor: '#E4E4E7' },
};

// The border is transparent by default, so a colored fill needs no matching `borderColor`.
const brand: ArcWidgetButtonData = {
  title: 'Publish',
  backgroundColor: '#2563EB',
  hoverActions: { backgroundColor: '#1D4ED8' },
};

const danger: ArcWidgetButtonData = {
  title: 'Delete',
  icon: <TrashIcon size={16} />,
  gap: '6px',
  backgroundColor: '#DC2626',
  hoverActions: { backgroundColor: '#B91C1C' },
};

export default function Example({ onDelete }: Props) {
  // Destructive action: ask before calling the handler.
  const confirmDelete = () => {
    if (window.confirm('Delete this record? This cannot be undone.')) onDelete?.();
  };

  const buttons = [
    { data: outline },
    { data: secondary },
    { data: brand },
    { data: danger, onClick: confirmDelete },
  ];

  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '12px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: buttons.map(({ data, onClick }) => ({
          width: 'auto',
          value: <ArcWidgetButton data={data} onClick={onClick} />,
        })),
      }}
    />
  );
}
```


## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Feuert beim Klick. Gib ein Promise zurück, damit `loading` sichtbar bleibt, bis es abgeschlossen ist.

```typescript
onClick?: () => void | Promise<void>;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### title

Fette Beschriftung; als Slot auch mit JSX möglich. Nutze `''` für Buttons nur mit Icon.

Typ: `ArcWidgetSlot`.

### subtitle

Kleinere zweite Beschriftung neben dem Titel.

Typ: `ArcWidgetSlot`.

### icon

Icon neben dem Titel, z. B. ein `ArcWidgetIcon`.

Typ: `ArcWidgetSlot`.

### prefix

Inhalt am Anfang, vor Icon und Titel.

Typ: `ArcWidgetSlot`.

### suffix

Inhalt am rechten Rand; braucht eine `width`, die breiter als der Inhalt ist.

Typ: `ArcWidgetSlot`.

### alignX

Horizontale Ausrichtung von Icon und Titel. Mit `prefix` oder `suffix` gilt sie für den Raum dazwischen. Standard: `center`.

Typ: `'left' | 'center' | 'right'`.

### alignY

Vertikale Ausrichtung des Inhalts, wenn `height` größer als der Inhalt ist. Standard: `center`.

Typ: `'top' | 'center' | 'bottom'`.

### iconPosition

Position des Icons relativ zum Titel. Standard: `left`.

Typ: `'left' | 'right' | 'top' | 'bottom'`.

### gap

Abstand zwischen Prefix, Icon, Titel, Badge und Suffix. Standard: `0` zwischen den Slots, `5px` zwischen Icon und Titel.

Typ: `string`.

### paddingX

Innerer Abstand links und rechts. Standard: `0.8em`.

Typ: `string`.

### paddingY

Innerer Abstand oben und unten. Standard: `0.5em`.

Typ: `string`.

### width

Breite des Buttons. Standard: `fit-content`.

Typ: `string`.

### height

Höhe des Buttons; `'auto'` behält die Inhaltshöhe. Standard: `auto`.

Typ: `string`.

### borderRadius

Abrundung der Ecken. Standard: `0.6em`.

Typ: `string`.

### borderColor

Farbe des 1px-Rahmens. Standard: transparent, der Rahmen übernimmt also die Hintergrundfarbe.

Typ: `string`.

### backgroundColor

Hintergrundfarbe. Standard: `#18181B`. Bei einer hellen Farbe auch `fontColor` setzen.

Typ: `string`.

### fontColor

Schriftfarbe; der Ladeindikator übernimmt sie. Standard: `#ffffff`.

Typ: `string`.

### fontSize

Schriftgröße als CSS-Wert; der Untertitel nutzt 80 % davon. Standard: `13px`.

Typ: `string`.

### hoverActions

Farben, solange der Mauszeiger über dem Button liegt (`fontColor`, `iconColor`, `backgroundColor`, `borderColor`), plus Übergangsdauer (`animation`, z. B. `"0.2s"`). Ohne Angabe wird nur der Standard-Look beim Hover heller; eine eigene `backgroundColor` behält ihre Farbe.

Typ: `ArcWidgetButtonHoverActions`.

### showBadge

Blendet das Badge ein. Standard: `false`.

Typ: `boolean`.

### badgeTitle

Inhalt des Badges, z. B. eine Anzahl.

Typ: `ArcWidgetSlot`.

### badgeColor

Schriftfarbe des Badges. Standard: `#ffffff`.

Typ: `string`.

### badgeBackground

Hintergrund des Badges. Standard: `#e9595d`.

Typ: `string`.

### badgeBorderColor

Rahmenfarbe des Badges. Standard: `#ffffff`.

Typ: `string`.

### badgePosition

`inside` setzt das Badge hinter den Titel; `outside` heftet es an die Ecke oben rechts. Standard: `inside`.

Typ: `'inside' | 'outside'`.

### badgeGap

Abstand vor einem innenliegenden Badge. Standard: `6px`, wenn `gap` nicht gesetzt ist, sonst `gap`.

Typ: `string`.

### loading

Ladezustand, solange das `onClick`-Promise läuft, aktiviert durch `show: true`. Zeigt einen Indikator im Button oder mit `overlay` eine zentrierte Karte. Einzelne Inhalte blendest du mit `hide` aus (`icon` akzeptiert zusätzlich `'auto'`). Der Indikator übernimmt die Schriftfarbe und wächst mit der Schriftgröße.

Typ: `ArcWidgetButtonLoading`.

## Navigation: AI Defaults

Für Navigation und beschriftete Aktionen empfehlen wir `alignX: 'left'`, `iconPosition: 'left'` und `gap: '8px'`. Die vorhandenen Runtime-Defaults bleiben unverändert. `alignY` steuert die vertikale Ausrichtung, `paddingX`/`paddingY` die Innenabstände.

Nutze `ArcWidgetIcon` mit `iconSet: 'phosphor'` als Icon-Slot. Dekorative Icons sollten mit `aria-hidden` und `pointerEvents: 'none'` eingebettet sein, damit sie die Button-Klicks nicht abfangen. Die [React-Vorlage](/docs/react/templates/react-starter) zeigt das vollständige Muster.

## 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: button -->
```typescript
export interface ArcWidgetButtonHoverActions {
	fontColor?: string;
	iconColor?: string;
	backgroundColor?: string;
	borderColor?: string;
	animation?: string;
}

export interface ArcWidgetButtonLoadingIndicator {
	type?: 'dots' | 'spinner' | 'pulse';
	color?: string;
	width?: string;
	height?: string;
}

export interface ArcWidgetButtonLoadingHide {
	icon?: boolean | 'auto';
	title?: boolean;
	subtitle?: boolean;
	badge?: boolean;
	prefix?: boolean;
	suffix?: boolean;
}

export interface ArcWidgetButtonLoadingStyles {
	fontColor?: string;
	iconColor?: string;
	backgroundColor?: string;
	borderColor?: string;
}

export interface ArcWidgetButtonOverlayText {
	value: string;
	styles?: string;
}

export interface ArcWidgetButtonOverlaySequence {
	after?: number;
	when?: boolean;
	priority?: number;
	title?: string | ArcWidgetButtonOverlayText;
	message?: string | ArcWidgetButtonOverlayText;
	indicator?: ArcWidgetButtonLoadingIndicator;
}

export interface ArcWidgetButtonOverlay {
	title?: string | ArcWidgetButtonOverlayText;
	message?: string | ArcWidgetButtonOverlayText;
	sequences?: ArcWidgetButtonOverlaySequence[];
	indicator?: ArcWidgetButtonLoadingIndicator;
	width?: string;
	height?: string;
	backgroundColor?: string;
}

export interface ArcWidgetButtonLoading {
	show?: boolean;
	indicator?: ArcWidgetButtonLoadingIndicator;
	hideOnFinish?: boolean;
	minDuration?: number;
	position?: 'left' | 'right' | 'prefix' | 'suffix';
	hideTitle?: boolean;
	hide?: ArcWidgetButtonLoadingHide;
	styles?: 'hover' | 'default' | ArcWidgetButtonLoadingStyles;
	overlay?: true | ArcWidgetButtonOverlay;
}

export interface ArcWidgetButtonData {
	title?: ArcWidgetSlot;
	subtitle?: ArcWidgetSlot;
	icon?: ArcWidgetSlot;
	prefix?: ArcWidgetSlot;
	suffix?: ArcWidgetSlot;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom';
	iconPosition?: 'left' | 'right' | 'top' | 'bottom';
	gap?: string;
	paddingX?: string;
	paddingY?: string;
	width?: string;
	height?: string;
	borderRadius?: string;
	borderColor?: string;
	backgroundColor?: string;
	fontColor?: string;
	fontSize?: string;
	hoverActions?: ArcWidgetButtonHoverActions;
	showBadge?: boolean;
	badgeTitle?: ArcWidgetSlot;
	badgeColor?: string;
	badgeBackground?: string;
	badgeBorderColor?: string;
	badgePosition?: 'inside' | 'outside';
	badgeGap?: string;
	loading?: ArcWidgetButtonLoading;
}

export interface ArcWidgetButtonProps extends ArcReactWidgetProps<ArcWidgetButtonData> {
	onClick?: () => void | Promise<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)
<!-- /host -->

<!-- host:ninox -->
# 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` sits on the right edge when the button has an explicit `width` (e.g. `"100%"`); `alignX` places the title between prefix and suffix. 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

![](https://framerusercontent.com/images/ILV64ahEXL4mvLmCRBdcVHiMc.png)

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

![](https://framerusercontent.com/images/hYjjWfJ7Ja9ldr3SBPThwgP3RiM.png)

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 von Icon und Titel im Button. Mit `prefix` oder `suffix` gilt sie für den Raum dazwischen. 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 sitzt am **rechten Rand**, sobald der Button eine explizite Breite hat (z. B. `width: "100%"`); `alignX` setzt den Titel in den Raum davor. 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%",
    alignX: "left",
    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:** <em>text
</em>**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 Weiß (`#ffffff`) verwendet. Der Ladeindikator übernimmt diese Farbe.

**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 fast Schwarz (`#18181B`). Bei einer hellen Farbe auch `fontColor` setzen.

**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, ist der Rahmen transparent und übernimmt so die Hintergrundfarbe.

**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 `0.6em`.

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

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`showBadge`

</td><td>*boolean*

</td><td>Legt fest, ob ein Badge angezeigt wird (`true` / `false`). Kann auch per Skript bestimmt werden: `if cnt(Dokumente)>0 then true end `

</td></tr><tr><td>`badgeTitle`

</td><td>*text*

</td><td>Text oder Zahl im Badge

</td></tr><tr><td>`badgeColor`

</td><td>*text*

</td><td>Textfarbe im Badge (z. B. `"#ffffff"`)

</td></tr><tr><td>`badgeBackground`

</td><td>*text*

</td><td>Hintergrundfarbe des Badges (z. B. `"#e9595d"`)

</td></tr><tr><td>`badgeBorderColor`

</td><td>*text*

</td><td>Rahmenfarbe des Badges (z. B. `"#ffffff"`)

</td></tr><tr><td>`badgePosition`

</td><td>*text*

</td><td>Zusätzliche Positionierung des Badges *(z. B. *`*"outside"*`* für Darstellung außerhalb des Buttons)*

</td></tr><tr><td>`badgeGap`

</td><td>*text*

</td><td>Abstand zwischen Button-Inhalt und Badge in der Standard-Position (Standard: `"6px"`). Wird bei `badgePosition: "outside"` nicht angewendet.

</td></tr></tbody></table></figure>### 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.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th><th>Beispielwert

</th></tr><tr><td>`fontColor`

</td><td>*text*

</td><td>Textfarbe beim Hover

</td><td>`"#ffffff"`

</td></tr><tr><td>`backgroundColor`

</td><td>*text*

</td><td>Hintergrundfarbe beim Hover

</td><td>`"#004C8A"`

</td></tr><tr><td>`borderColor`

</td><td>*text*

</td><td>Rahmenfarbe beim Hover

</td><td>`"#003366"`

</td></tr><tr><td>`iconColor`

</td><td>*text*

</td><td>Farbe des Icons beim Hover (nur bei SVG-Icons relevant)

</td><td>`"#ffffff"`

</td></tr><tr><td>`animation`

</td><td>*text*

</td><td>CSS-Transition-Zeit für sanfte Effekte

</td><td>`"0.25s"`

</td></tr></tbody></table></figure>### 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

<figure><table><tbody><tr><th>`type`

</th><th>Beschreibung

</th><th>Code-Beispiel

</th></tr><tr><td>`"openUrl"`

</td><td>Öffnet einen externen Link in einem neuen Tab

</td><td>
```javascript
{type: "openUrl",
value: "https://example.com" }
```

</td></tr><tr><td>`"openRecord"`

</td><td>Öffnet einen bestehenden Datensatz im aktuellen Fenster

</td><td>
```javascript
{ type: "openRecord",
  recordId: first(select Dashboard).Nr}
```

</td></tr><tr><td>`"openFullscreen"`

</td><td>Öffnet einen Datensatz im Vollbild-Modus

</td><td>
```javascript
{ type: "openFullscreen",
  recordId: Nr,
  tab: "Details" }
```

</td></tr><tr><td>`"popup"`

</td><td>Öffnet einen Datensatz als Popup

</td><td>
```javascript
{ type: "popup",
recordId: Nr,
tab: "Info" }
```

</td></tr><tr><td>`"closeRecord"`

</td><td>Schließt den aktuellen Datensatz

</td><td>
```javascript
{ type: "closeRecord",
  recordId: Nr }
```

</td></tr><tr><td>`"closeFullscreen"`

</td><td>Schließt den Vollbildmodus

</td><td>
```javascript
{ type: "closeFullscreen",
  recordId: Nr }
```

</td></tr><tr><td>`"closeAllRecords"`

</td><td>Schließt alle geöffneten Datensätze

</td><td>
```javascript
{ type: "closeAllRecords" }
```

</td></tr><tr><td>`"delete"`

</td><td>Löscht den angegebenen Datensatz

</td><td>
```javascript
{ type: "delete",
recordId: Nr }
```

</td></tr><tr><td>`"update"`

</td><td>Aktualisiert ein Feld in einem Datensatz

</td><td>
```javascript
{ type: "update",
recordId: Auftrag.Nr,
field: "A1",
value: "Erledigt" }
```

</td></tr><tr><td>`"create"`

</td><td>Erstellt einen neuen Datensatz mit optionalem Popup

</td><td>
```javascript
{ type: "create",
tableId: "A",
popup: true,
changeFieldValues: [{ fieldId: "AZ",
                      value: "Neu" }] }
```

</td></tr><tr><td>`"customJS"`

</td><td>Führt benutzerdefinierten JavaScript-Code aus

</td><td>
```javascript
{ type: "customJS",
value: "alert('Hallo Welt!');" }
```

</td></tr></tbody></table></figure>💡 *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, mit `alignX: "left"` bleibt der Text 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 | Schriftfarbe (Button) / `#4970ff` (Overlay) | Farbe |
| `width` | text | wächst mit der Schriftgröße (Button) / `60px` (Overlay) | CSS-Breite |
| `height` | text | wächst mit der Schriftgröße (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.
<!-- /host -->

<!-- host:vue -->
# 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` sits on the right edge when the button has an explicit `width` (e.g. `"100%"`); `alignX` places the title between prefix and suffix. 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

![](https://framerusercontent.com/images/ILV64ahEXL4mvLmCRBdcVHiMc.png)

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

![](https://framerusercontent.com/images/hYjjWfJ7Ja9ldr3SBPThwgP3RiM.png)

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 von Icon und Titel im Button. Mit `prefix` oder `suffix` gilt sie für den Raum dazwischen. 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 sitzt am **rechten Rand**, sobald der Button eine explizite Breite hat (z. B. `width: "100%"`); `alignX` setzt den Titel in den Raum davor. 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%",
    alignX: "left",
    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:** <em>text
</em>**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 Weiß (`#ffffff`) verwendet. Der Ladeindikator übernimmt diese Farbe.

**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 fast Schwarz (`#18181B`). Bei einer hellen Farbe auch `fontColor` setzen.

**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, ist der Rahmen transparent und übernimmt so die Hintergrundfarbe.

**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 `0.6em`.

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

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`showBadge`

</td><td>*boolean*

</td><td>Legt fest, ob ein Badge angezeigt wird (`true` / `false`). Kann auch per Skript bestimmt werden: `if cnt(Dokumente)>0 then true end `

</td></tr><tr><td>`badgeTitle`

</td><td>*text*

</td><td>Text oder Zahl im Badge

</td></tr><tr><td>`badgeColor`

</td><td>*text*

</td><td>Textfarbe im Badge (z. B. `"#ffffff"`)

</td></tr><tr><td>`badgeBackground`

</td><td>*text*

</td><td>Hintergrundfarbe des Badges (z. B. `"#e9595d"`)

</td></tr><tr><td>`badgeBorderColor`

</td><td>*text*

</td><td>Rahmenfarbe des Badges (z. B. `"#ffffff"`)

</td></tr><tr><td>`badgePosition`

</td><td>*text*

</td><td>Zusätzliche Positionierung des Badges *(z. B. *`*"outside"*`* für Darstellung außerhalb des Buttons)*

</td></tr><tr><td>`badgeGap`

</td><td>*text*

</td><td>Abstand zwischen Button-Inhalt und Badge in der Standard-Position (Standard: `"6px"`). Wird bei `badgePosition: "outside"` nicht angewendet.

</td></tr></tbody></table></figure>### 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.

<figure><table><tbody><tr><th>Feld

</th><th>Typ

</th><th>Beschreibung

</th><th>Beispielwert

</th></tr><tr><td>`fontColor`

</td><td>*text*

</td><td>Textfarbe beim Hover

</td><td>`"#ffffff"`

</td></tr><tr><td>`backgroundColor`

</td><td>*text*

</td><td>Hintergrundfarbe beim Hover

</td><td>`"#004C8A"`

</td></tr><tr><td>`borderColor`

</td><td>*text*

</td><td>Rahmenfarbe beim Hover

</td><td>`"#003366"`

</td></tr><tr><td>`iconColor`

</td><td>*text*

</td><td>Farbe des Icons beim Hover (nur bei SVG-Icons relevant)

</td><td>`"#ffffff"`

</td></tr><tr><td>`animation`

</td><td>*text*

</td><td>CSS-Transition-Zeit für sanfte Effekte

</td><td>`"0.25s"`

</td></tr></tbody></table></figure>### 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

<figure><table><tbody><tr><th>`type`

</th><th>Beschreibung

</th><th>Code-Beispiel

</th></tr><tr><td>`"openUrl"`

</td><td>Öffnet einen externen Link in einem neuen Tab

</td><td>
```javascript
{type: "openUrl",
value: "https://example.com" }
```

</td></tr><tr><td>`"openRecord"`

</td><td>Öffnet einen bestehenden Datensatz im aktuellen Fenster

</td><td>
```javascript
{ type: "openRecord",
  recordId: first(select Dashboard).Nr}
```

</td></tr><tr><td>`"openFullscreen"`

</td><td>Öffnet einen Datensatz im Vollbild-Modus

</td><td>
```javascript
{ type: "openFullscreen",
  recordId: Nr,
  tab: "Details" }
```

</td></tr><tr><td>`"popup"`

</td><td>Öffnet einen Datensatz als Popup

</td><td>
```javascript
{ type: "popup",
recordId: Nr,
tab: "Info" }
```

</td></tr><tr><td>`"closeRecord"`

</td><td>Schließt den aktuellen Datensatz

</td><td>
```javascript
{ type: "closeRecord",
  recordId: Nr }
```

</td></tr><tr><td>`"closeFullscreen"`

</td><td>Schließt den Vollbildmodus

</td><td>
```javascript
{ type: "closeFullscreen",
  recordId: Nr }
```

</td></tr><tr><td>`"closeAllRecords"`

</td><td>Schließt alle geöffneten Datensätze

</td><td>
```javascript
{ type: "closeAllRecords" }
```

</td></tr><tr><td>`"delete"`

</td><td>Löscht den angegebenen Datensatz

</td><td>
```javascript
{ type: "delete",
recordId: Nr }
```

</td></tr><tr><td>`"update"`

</td><td>Aktualisiert ein Feld in einem Datensatz

</td><td>
```javascript
{ type: "update",
recordId: Auftrag.Nr,
field: "A1",
value: "Erledigt" }
```

</td></tr><tr><td>`"create"`

</td><td>Erstellt einen neuen Datensatz mit optionalem Popup

</td><td>
```javascript
{ type: "create",
tableId: "A",
popup: true,
changeFieldValues: [{ fieldId: "AZ",
                      value: "Neu" }] }
```

</td></tr><tr><td>`"customJS"`

</td><td>Führt benutzerdefinierten JavaScript-Code aus

</td><td>
```javascript
{ type: "customJS",
value: "alert('Hallo Welt!');" }
```

</td></tr></tbody></table></figure>💡 *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, mit `alignX: "left"` bleibt der Text 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 | Schriftfarbe (Button) / `#4970ff` (Overlay) | Farbe |
| `width` | text | wächst mit der Schriftgröße (Button) / `60px` (Overlay) | CSS-Breite |
| `height` | text | wächst mit der Schriftgröße (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
<ArcWidgetButton id="save" :data="buttonData" @action="handleAction" />
```
<!-- /host -->


---

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

<iframe src="https://www.youtube.com/embed/uxDppTcWZjE?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## 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

![](https://framerusercontent.com/images/Qk8oDQFM0sGgNWLRGHjWMzkbw.png)


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

![](https://framerusercontent.com/images/n9PTr1k2xJeCKvO0ro0nydihE0s.png)

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:**

<figure><table><tbody><tr><th>Paramter

</th><th>**Beschreibung**

</th></tr><tr><td>visible

</td><td>Zeigt die Legende an (`true`) oder blendet sie aus (`false`).

</td></tr><tr><td>position

</td><td>Platzierung: `"left"`, `"right"`, `"top"` oder `"bottom"`

</td></tr><tr><td>label

</td><td>Was soll in der Legende stehen? Ninox Felder referenzieren oder eigene Textbezeichnungen wählen.

</td></tr><tr><td>fontSize

</td><td>Schriftgröße der Labels, z. B. `"12px"`

</td></tr><tr><td>fontWeight

</td><td>Schriftstärke: `"normal"`, `"bold"`, `"500"` usw.

</td></tr><tr><td>fontColor

</td><td>Farbe des Legendentextes, z. B. `"#333"`

</td></tr><tr><td>gap

</td><td>Abstand zwischen den Einträgen, z. B. `"6px"`

</td></tr></tbody></table></figure>


## 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:**

<figure><table><tbody><tr><th>Paramter

</th><th>**Beschreibung**

</th></tr><tr><td>title

</td><td>Haupttext in der Mitte (z. B. „Gesamt“)

</td></tr><tr><td>subtitle

</td><td>Untertitel direkt darunter (z. B. eine Zahl oder Status)

</td></tr><tr><td>fontSize

</td><td>Größe beider Texte (gilt für beide), z. B. `"18px"`

</td></tr><tr><td>fontColor

</td><td>Farbe der Schrift, z. B. `"#444"`

</td></tr></tbody></table></figure>
```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.

![](https://framerusercontent.com/images/XLOC8UfDRKQjhqx744eb1JzUyzE.png)

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.

![](https://framerusercontent.com/images/jAD8j5G4Qgu7GtaCjoiDP1bY9M.png)


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

![](https://framerusercontent.com/images/wfBxaQXtgMGbuMqspjDQqv7ctyY.png)


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

![](https://framerusercontent.com/images/rj8oX1OsPhULE3w0y0g1IWQc0N4.png)


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

![](https://framerusercontent.com/images/K8ruoQIAIdeaw7M5uBdQO25vPI.png)


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

![](https://framerusercontent.com/images/523K0a0Mt7UdM3HrTWvPKC9qRA.png)


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

![](https://framerusercontent.com/images/glD2dnfE8bprWD18aeK5wPt5nfw.png)


```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)**.**

![](https://framerusercontent.com/images/z36FQ2pPqaAf2qyFUZpe2sv44cc.png)

**Vorlage: Anwendungs-Code mit dynamischem Label**

Du kannst dir folgenden Code kopieren und mit kleinen Anpassungen, hast du dieses fertige Design mit dynamischem Label:

![](https://framerusercontent.com/images/A5ZtSy9EUovXWfWuVKvxO68oU.png)

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

![](https://framerusercontent.com/images/IvCDlbWt9G420AliTTvz2wZ0JwU.png)

## 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
	})
```

![](https://framerusercontent.com/images/3TQuxxR7rg5PIDGt4sudFz8auUA.png)

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


<!-- host:react -->
# 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



## Features ausprobieren

### Symbol, Strichstärke und Größe

Wechsle zwischen Phosphor-Symbolen und Varianten. Das Beispiel verwendet die reale Icon-Laufzeit inklusive SVG-Laden.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Icon-Familie. Standard: `phosphor`.

Typ: `'phosphor' | 'material_symbols'`.

### name

Name des Symbols im gewählten Set, z. B. `'user'`.

Typ: `string`.

### style

Variante des Symbols. Phosphor: `regular` (Standard), `bold`, `fill`, `thin`, `light`, `duotone`. Material Symbols: `outlined` (Standard), `outlined-fill`, `rounded`, `rounded-fill`, `sharp`, `sharp-fill`.

Typ: `string`.

### iconSize

Breite und Höhe des Symbols. Standard: `15px`.

Typ: `string`.

### color

Füllfarbe des Symbols.

Typ: `string`.

### containerSize

Breite und Höhe der Fläche um das Symbol; das Symbol sitzt darin zentriert.

Typ: `string`.

### backgroundColor

Hintergrund der Fläche um das Symbol.

Typ: `string`.

### borderRadius

Abrundung der Ecken der Fläche.

Typ: `string`.

### borderSize

Rahmenstärke der Fläche, z. B. `'1px'`. Standard: `0px`.

Typ: `string`.

### borderColor

Rahmenfarbe der Fläche. Standard: `#000`.

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

## Feste Icons oder dynamische Namen

Für Icons, die fest im Code stehen, nutze das offizielle Paket `@phosphor-icons/react` und übergib das Icon als JSX in einen Slot, etwa Button-`icon`, Layout-Block-`value` oder ein Karten-Layout. Die Icons werden Teil deines App-Bundles: Nur importierte Icons landen darin, TypeScript prüft die Namen, und es wird kein externer Server angesprochen.

```bash
npm install @phosphor-icons/react
```

```tsx
import { ArcWidgetButton } from '@arcrider/arcwidgets-react';
import { PlusIcon } from '@phosphor-icons/react';

export default function Example() {
  return (
    <ArcWidgetButton
      data={{ title: 'Add', icon: <PlusIcon size={16} />, iconPosition: 'left' }}
    />
  );
}
```

Das Icon übernimmt die Textfarbe des umgebenden Widgets (`currentColor`); `weight="fill"` wählt die gefüllte Variante.

`ArcWidgetIcon` ist für Icons gedacht, deren Name erst zur Laufzeit feststeht, zum Beispiel aus deinen Daten oder von Nutzern gewählt. Es lädt das Icon beim ersten Anzeigen.

## Icon-Quelle, Datenschutz und Selbst-Hosting

Beim ersten Anzeigen eines Icons wird sein SVG vom Arc-Rider-CDN (`https://universe.arc-rider.com/cdn/`) geladen und im Browser gespeichert, sodass jedes Icon pro Browser nur einmal angefragt wird. So stehen die kompletten Kataloge von Phosphor und Material Symbols ohne Installation bereit: Nutze einen beliebigen Icon-Namen von [phosphoricons.com](https://phosphoricons.com) oder [fonts.google.com/icons](https://fonts.google.com/icons).

- **Datenschutz:** Jede Anfrage übermittelt die IP-Adresse der Besucher an die Arc Rider Ventures GmbH, wie bei jeder externen Web-Ressource. Führt deine Datenschutzerklärung Drittdienste auf, ergänze `universe.arc-rider.com` oder lade die Icons von deinem eigenen Server (siehe unten). Im Zweifel frag deinen Datenschutzbeauftragten.
- **Content Security Policy:** Erlaube `https://universe.arc-rider.com` in `connect-src`.
- **Unbekannte Namen:** Ein falsch geschriebener Name oder Style zeigt nichts an und schreibt eine Warnung mit der angefragten URL in die Browser-Konsole. Fehlgeschlagene Downloads werden nie gespeichert.
- **Sicherheit:** Heruntergeladene Dateien werden vor dem Einfügen auf reine Formen reduziert; Skripte, Event-Handler, Inline-Styles und externe Verweise werden entfernt.
- **Aktualisierung:** Zwischengespeicherte Icons werden automatisch erneuert, wenn ein Paket-Release die Icon-Dateien aktualisiert.

Um die Icons selbst auszuliefern, kopiere die Dateien in einen statischen Ordner deiner App und rufe `configureIcons` einmal beim App-Start auf, bevor das erste Icon gerendert wird. Ein Aufruf ohne Optionen stellt das Arc-Rider-CDN wieder her.

```tsx
import { configureIcons } from '@arcrider/arcwidgets-react';

configureIcons({
  phosphorBaseUrl: '/icons/phosphor',
  materialSymbolsBaseUrl: '/icons/material',
});
```

```bash
npm install @phosphor-icons/core @material-symbols/svg-400
cp -r node_modules/@phosphor-icons/core/assets public/icons/phosphor
cp -r node_modules/@material-symbols/svg-400 public/icons/material
```

Jeder Ordner muss die Style-Ordner enthalten (`regular`, `bold`, `fill` … bei Phosphor; `outlined`, `rounded`, `sharp` bei Material Symbols).

**Lizenzen:** Phosphor Icons (MIT) und Material Symbols (Apache 2.0) dürfen in kommerziellen Apps genutzt werden; kopierst du die Dateien, behalte die mitgelieferten Lizenztexte.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: icon -->
```typescript
export interface ArcWidgetIconData {
	iconSet?: 'phosphor' | 'material_symbols';
	name: string;
	style?: string;
	iconSize?: string;
	color?: string;
	containerSize?: string;
	backgroundColor?: string;
	borderRadius?: string;
	borderSize?: string;
	borderColor?: string;
}

export interface ArcWidgetIconProps extends ArcReactWidgetProps<ArcWidgetIconData> {}

export interface ArcConfigureIconsOptions {
	phosphorBaseUrl?: string;
	materialSymbolsBaseUrl?: string;
}

export declare function configureIcons(options?: ArcConfigureIconsOptions): void;
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# 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).

![](https://framerusercontent.com/images/BQHL1tv8vsJu3xvmoxcMkFDA.png)

![](https://framerusercontent.com/images/hfUtTFBevtvrRjhCZgPJeyouqY.png)

![](https://framerusercontent.com/images/yHkFmJcBcApLpAZQeVoujOs6c.png)

##

Anwendungscode

![](https://framerusercontent.com/images/6vH4hAeFxzFpJt5B4RKfjE4bRZ8.png)


```javascript
arcCustomIcon({
        iconSet: "phosphor",
        name: "trash",
        containerSize: "40px",
        borderSize: "",
        borderColor: "",
        borderRadius: "7px",
        iconSize: "30px",
        color: "#FF2222",
        backgroundColor: "#fcdfde"
    })
```

![](https://framerusercontent.com/images/6F2gYfjUBFLwVTpV4t7gEDcVsMo.png)


```javascript
arcCustomIcon({
    iconSet: "openmoji",
    name: "envelope-with-arrow-color",
    containerSize: "50px",
    borderSize: "1px",
    borderColor: "",
    iconSize: "50px",
    borderRadius: "50px",
    color: "#C637E4",
    backgroundColor: "#FAE6FF"
}),
```

<em><strong>

iconSet</strong></em> 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.

<em><strong>style</strong></em> (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" })
```

<em><strong>
name</strong></em> 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.

![](https://framerusercontent.com/images/Gd2H3UKMxrORUpsAvOzylXWDAM.png)
<!-- /host -->


---

# Images

Source: https://www.arc-rider.com/docs/mini-widgets/images


<!-- host:react -->
# Image in React

Zeigt ein Foto, Logo oder Avatar in Tabellen, Karten, Kanban und Layouts. Die Box behält ihre Form, während das Bild lädt, und ein Platzhalter erscheint, wenn es kein Bild gibt oder die URL nicht lädt.

Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.7`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).

## AI Defaults (read first)

- `value` ist die Bild-URL oder eine Data-URL (`data:image/png;base64,…`).
- `alt` für Bilder setzen, die Inhalt tragen. Ohne `alt` wird `title` verwendet; ohne beides gilt das Bild als dekorativ.
- Ohne `width` / `height` erscheint das Bild in seiner natürlichen Größe, nie breiter als sein Container.
- Für Vorschaubilder und Avatare `width` und `height` setzen und `objectFit: 'cover'` verwenden. Der Standard `contain` zeigt das ganze Bild.
- Profile ohne Foto: `initials` setzen (z. B. `'JJ'`) und die Person in `alt` benennen. Die Buchstaben erscheinen, solange es kein Bild gibt oder es nicht lädt, nie während des Ladens.
- Für Karten `aspectRatio` (z. B. `'16/9'`) statt einer festen `height` nehmen: Die Box nimmt die volle Breite und behält ihre Form, bevor das Bild geladen ist.
- Abrundung und Linien gehören in `border` (`radius: '50%'` für einen Kreis), nicht in `styles`.
- Bilder laden erst, wenn sie ins Bild scrollen. `loading: 'eager'` nur für das erste sichtbare Bild einer Seite.

## Vollständiges Beispiel

<!-- react-example: image-03-card_ratio.tsx -->
```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// Generated landscapes in different sizes keep the example offline.
const photo = (width: number, height: number, color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    `<svg xmlns='http://www.w3.org/2000/svg' width='${width}' height='${height}'>` +
      `<rect width='${width}' height='${height}' fill='${color}'/>` +
      `<path d='M0 ${height} L${width * 0.35} ${height * 0.45} L${width * 0.6} ${height * 0.75} L${width} ${height * 0.4} L${width} ${height} Z' fill='#18181B' fill-opacity='0.5'/>` +
      '</svg>',
  )}`;

const projects = [
  { title: 'North site', image: photo(1600, 900, '#38BDF8') },
  { title: 'Harbor depot', image: photo(800, 800, '#A78BFA') },
  { title: 'City office', image: photo(700, 1000, '#FB923C') },
];

export default function Example() {
  // The images have different shapes, the cards do not: `aspectRatio` fixes the box
  // to 16:9 at the full card width before anything loads, and `cover` fills it.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignY: 'top',
        width: '100%',
        height: '100%',
        gap: '16px',
        paddingX: '24px',
        paddingY: '24px',
        backgroundColor: '#F4F4F5',
        blocks: projects.map((project) => ({
          width: 'fraction',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                gap: '10px',
                paddingX: '10px',
                paddingY: '10px',
                backgroundColor: '#FFFFFF',
                border: { color: '#E4E4E7', radius: '12px' },
                blocks: [
                  {
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: project.image,
                          alt: project.title,
                          aspectRatio: '16/9',
                          objectFit: 'cover',
                          border: { radius: '8px' },
                        }}
                      />
                    ),
                  },
                  {
                    value: (
                      <ArcWidgetText
                        data={{ value: project.title, fontSize: '14px', fontWeight: 600 }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Funktionen ausprobieren

Jedes Beispiel setzt nur die Werte, die die Variante ausmachen.

### Natürliche Größe

Nur `value` und `alt` sind gesetzt. Das Bild ist so groß wie seine Datei, höchstens so breit wie sein Container.

<!-- react-example: image-00-defaults.tsx -->
```tsx
import { ArcWidgetImage, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

// A generated landscape keeps the example offline. Any image URL or data URL works.
const photo = `data:image/svg+xml,${encodeURIComponent(
  "<svg xmlns='http://www.w3.org/2000/svg' width='1200' height='800'>" +
    "<rect width='1200' height='800' fill='#6366F1'/>" +
    "<circle cx='860' cy='240' r='96' fill='#FDE68A'/>" +
    "<path d='M0 800 L420 360 L720 600 L940 460 L1200 800 Z' fill='#18181B' fill-opacity='0.55'/>" +
    '</svg>',
)}`;

export default function Example() {
  // Only the source is set on the image. It shows at its natural size,
  // never wider than its container, so it shrinks with the window.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        paddingX: '24px',
        paddingY: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: [
          {
            width: 'fraction',
            alignX: 'center',
            value: (
              <ArcWidgetImage
                data={{ value: photo, alt: 'Mountain landscape' }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Einpassen und Zuschneiden

Dasselbe Hochformat in derselben Box. `objectFit` bestimmt, wie es die Box füllt, `objectPosition`, welcher Teil sichtbar bleibt.

<!-- react-example: image-01-fit.tsx -->
```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// A generated portrait photo keeps the example offline.
const photo = `data:image/svg+xml,${encodeURIComponent(
  "<svg xmlns='http://www.w3.org/2000/svg' width='600' height='900'>" +
    "<rect width='600' height='900' fill='#F472B6'/>" +
    "<circle cx='300' cy='200' r='90' fill='#FDE68A'/>" +
    "<path d='M0 900 L180 520 L360 760 L460 620 L600 900 Z' fill='#18181B' fill-opacity='0.55'/>" +
    '</svg>',
)}`;

// The same portrait in the same 200 x 140 box. `objectFit` decides how it fills the box,
// `objectPosition` which part stays visible when it is cropped.
const variants = [
  { label: 'contain (default)', data: {} },
  { label: 'cover', data: { objectFit: 'cover' as const } },
  { label: 'cover, top', data: { objectFit: 'cover' as const, objectPosition: 'top' } },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '24px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: variants.map((variant) => ({
          width: 'auto',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                alignX: 'center',
                gap: '8px',
                blocks: [
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: photo,
                          alt: 'Portrait photo',
                          width: '200px',
                          height: '140px',
                          backgroundColor: '#E4E4E7',
                          border: { radius: '10px' },
                          ...variant.data,
                        }}
                      />
                    ),
                  },
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetText
                        data={{ value: variant.label, fontSize: '13px', fontColor: '#52525B' }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

### Avatare

Eine quadratische Box mit `border.radius: '50%'` und `objectFit: 'cover'` ergibt einen runden Avatar. Für Personen ohne Foto erscheinen `initials` statt des Platzhalter-Icons; die Buchstaben wachsen mit der Box.

<!-- react-example: image-02-avatars.tsx -->
```tsx
import { ArcWidgetImage, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

// Generated square portraits keep the example offline.
const portrait = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    "<svg xmlns='http://www.w3.org/2000/svg' width='256' height='256'>" +
      `<rect width='256' height='256' fill='${color}'/>` +
      "<circle cx='128' cy='104' r='48' fill='#FFFFFF' fill-opacity='0.9'/>" +
      "<path d='M40 256 C40 190 216 190 216 256 Z' fill='#FFFFFF' fill-opacity='0.9'/>" +
      '</svg>',
  )}`;

// `photo` is missing for some people: their `initials` take the place of the image.
const team = [
  { name: 'Alex Morgan', initials: 'AM', color: '#6366F1', photo: true },
  { name: 'Sam Lee', initials: 'SL', color: '#0EA5E9', photo: true },
  { name: 'Robin Diaz', initials: 'RD', color: '#F59E0B', photo: false },
  { name: 'Kim Novak', initials: 'KN', color: '#10B981', photo: false },
];

export default function Example() {
  // A square box with `radius: '50%'` gives a circle; `cover` fills it without distortion.
  // `title` names each person on hover; `alt` names them for screen readers.
  // Without a photo, or when it fails to load, `initials` show instead of the placeholder icon.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '8px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: team.map((member) => ({
          width: 'auto',
          value: (
            <ArcWidgetImage
              data={{
                value: member.photo ? portrait(member.color) : undefined,
                alt: member.name,
                title: member.name,
                initials: member.initials,
                backgroundColor: '#E4E4E7',
                width: '48px',
                height: '48px',
                objectFit: 'cover',
                border: { color: '#E4E4E7', radius: '50%' },
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

### Platzhalter

Ohne `value` oder wenn die URL nicht lädt, behält die Box ihre Größe und zeigt ein Platzhalter-Icon.

<!-- react-example: image-04-placeholder.tsx -->
```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// Without `value`, or when the URL fails to load, the box keeps its size
// and shows a placeholder icon instead of a broken-image symbol.
const cases = [
  { label: 'No image yet', value: '' },
  { label: 'URL fails to load', value: 'https://invalid.example/missing.jpg' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: cases.map((item) => ({
          width: 'auto',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                alignX: 'center',
                gap: '8px',
                blocks: [
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: item.value,
                          alt: 'Product photo',
                          width: '120px',
                          height: '120px',
                          border: { radius: '12px' },
                        }}
                      />
                    ),
                  },
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetText
                        data={{ value: item.label, fontSize: '13px', fontColor: '#52525B' }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Für die normale Nutzung nicht nötig; wird automatisch erzeugt.

### data

Konfiguration vom Typ `ArcWidgetImageData`. Änderungen als neue Objekte übergeben.

### onAction

Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Das Image löst selbst keine Ereignisse aus; für Klicks steckst du es in einen Button, einen klickbaren Grid-Block oder einen Layout-Block. Details: [State und Events](/docs/react/patterns/react-state-events).

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben.

### value

Bild-URL oder Data-URL. Ohne Wert erscheint der Platzhalter.

Typ: `string`.

### alt

Textalternative für Screenreader. Standard: `title`. Bei rein dekorativen Bildern beides leer lassen.

Typ: `string`.

### title

Tooltip beim Überfahren mit der Maus.

Typ: `string`.

### width

Breite der Box, z. B. `"80px"` oder `"100%"`. Standard: die Bildbreite, höchstens die Containerbreite.

Typ: `string`.

### height

Höhe der Box, z. B. `"80px"`. Standard: folgt dem Bild.

Typ: `string`.

### aspectRatio

Seitenverhältnis der Box, z. B. `"16/9"` oder `"1"`. Die Box nimmt `width` (Standard: volle Breite), die Höhe folgt dem Verhältnis. Sind `width` und `height` beide gesetzt, wird das Verhältnis ignoriert.

Typ: `string`.

### objectFit

Wie das Bild eine Box mit fester Größe füllt. `contain` zeigt alles, `cover` füllt die Box und schneidet zu, `fill` verzerrt, `none` behält die Originalgröße, `scale-down` nimmt das Kleinere aus `none` und `contain`. Standard: `contain`.

Typ: `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`.

### objectPosition

Welcher Teil des Bildes sichtbar bleibt, wenn es zugeschnitten oder kleiner als die Box ist, z. B. `"top"` oder `"50% 20%"`. Standard: `center`.

Typ: `string`.

### backgroundColor

Hintergrund der Box, sichtbar um ein `contain`-Bild und hinter transparenten Pixeln. Standard: transparent. Beim Laden und im Platzhalter ist die Box hellgrau, solange dieser Wert nicht gesetzt ist.

Typ: `string`.

### initials

Kurzes Kürzel, das statt des Platzhalter-Icons erscheint, solange es kein Bild gibt oder es nicht lädt, z. B. `'JJ'` für ein Profil. Wird in Großbuchstaben angezeigt, höchstens drei Zeichen, passend zur Boxgröße. Die Person für Screenreader in `alt` benennen.

Typ: `string`.

### fontColor

Farbe der `initials`. Standard: dunkelgrau.

Typ: `string`.

### border

Linie und Eckenradius der Box: `color`, `width`, `style`, `radius` und `sides`. Die Linie erscheint, sobald `color`, `width`, `style` oder `sides` gesetzt ist; `radius` allein rundet nur die Ecken und schneidet das Bild passend zu.

Typ: `ArcWidgetImageBorder`.

### loading

`lazy` lädt das Bild, wenn es ins Bild scrollt, `eager` sofort. Standard: `lazy`.

Typ: `'lazy' | 'eager'`.

### styles

CSS-Deklarationen, die zuletzt auf die Box angewendet werden, z. B. `'opacity: 0.6'`.

Typ: `string`.

## Verhalten und Grenzen

- Das Widget rendert ein echtes `<img>`-Element: Der Browser dekodiert es abseits des Hauptthreads, lädt es bei Bedarf und liest `alt` für Screenreader vor.
- Ein Bild, das nicht lädt, zeigt den Platzhalter statt des Browser-Symbols für defekte Bilder. Die Box behält die gesetzte Größe; ohne Größe ist der Platzhalter `48px` groß.
- `initials` ersetzen das Platzhalter-Icon nur, solange es kein Bild gibt oder es nicht geladen werden konnte. Während des Ladens bleibt die Box ruhig grau. Die Schriftgröße folgt der Box; mit `--arc-image-initials-size` (z. B. `14px`) auf dem Image oder einem Eltern-Element lässt sie sich festlegen.
- Die Platzhalter-Farben folgen den CSS-Variablen `--arc-image-placeholder-bg`, `--arc-image-placeholder-color` und `--arc-image-placeholder-size`. Auf einem Eltern-Element gesetzt, gelten sie für alle Bilder darin.
- Das Image gehört in Inhalts-Slots wie `blocks[].value` oder Tabellenzellen. Einen eigenen Klick-Callback hat es nicht.

## Datentypen

Die folgenden widget-bezogenen Typen exportiert das Paket. Gemeinsame Typen wie `ArcReactWidgetProps` sind ebenfalls verfügbar. Konfigurationsobjekte sind geschlossen, ein falsch geschriebener oder nicht unterstützter Schlüssel ist also ein Typfehler.

<!-- react-types: image -->
```typescript
export interface ArcWidgetImageBorder {
	color?: string;
	width?: string;
	style?: 'solid' | 'dashed' | 'dotted' | 'double';
	radius?: string;
	sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}

export interface ArcWidgetImageData {
	value?: string;
	alt?: string;
	title?: string;
	width?: string;
	height?: string;
	aspectRatio?: string;
	objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
	objectPosition?: string;
	backgroundColor?: string;
	initials?: string;
	fontColor?: string;
	border?: ArcWidgetImageBorder;
	loading?: 'lazy' | 'eager';
	styles?: string;
}

export interface ArcWidgetImageProps extends ArcReactWidgetProps<ArcWidgetImageData> {}
```

## Anwendungsbeispiele

- [Komposition und Layout](/docs/react/patterns/nested-widget-descriptors)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# Images

## AI Defaults (read first)

- **Function name**: `arcCustomImage`.
- **value**: Bild-URL, Ninox-Share-Link oder Data-URL. Ältere Formeln mit `link` funktionieren weiter.
- **uniqueId**: pro Bild eindeutig, z. B. `"ProjektBild" + Nr`.
- **alt**: Textalternative für Screenreader; ohne `alt` wird `title` verwendet.
- **width**, **height**: Größe der Box. Ohne beides erscheint das Bild in natürlicher Größe, höchstens so breit wie der Container.
- **initials**: Kürzel statt Platzhalter-Icon, solange es kein Bild gibt oder es nicht lädt, z. B. `initials: substr(text(Vorname), 0, 1) + substr(text(Nachname), 0, 1)`. Dazu die Person in **alt** benennen.
- **objectFit**: `"cover"` (füllt und schneidet zu) oder `"contain"` (zeigt alles, Standard). Ältere Formeln mit `backgroundSize` funktionieren weiter.
- **border**: `{ color, width, style, radius, sides }`, z. B. `border: { radius: "50%" }` für einen Kreis. Ältere Formeln mit `radius` / `borderColor` funktionieren weiter.

# Custom Image

![](https://framerusercontent.com/images/h6ypxIbc4vHFWhQqTPFfWjn1k.png)

Mit Images zeigst du Bilder in Tabellen, Kanban, Layouts oder anderen Widgets: Fotos, Logos, Avatare. Die Box behält ihre Größe, während das Bild lädt. Gibt es kein Bild oder lädt die URL nicht, erscheint ein Platzhalter-Icon.

```javascript
arcCustomImage({
    uniqueId: "ProjektBild" + Nr,
    value: text(Projekt.'Bild URL'),
    alt: "Projektfoto",
    title: "Projektfoto",
    width: "80px",
    height: "80px",
    objectFit: "cover",
    border: {
        color: "#E4E4E7",
        radius: "8px"
    }
})
```

### Bestehende Formeln

Formeln mit den bisherigen Parametern laufen unverändert weiter. Sie werden so übersetzt:

| Bisher | Jetzt |
|---|---|
| `link` | `value` |
| `backgroundSize: "cover"` / `"contain"` | `objectFit: "cover"` / `"contain"` |
| `backgroundSize: "auto"` | `objectFit: "none"` |
| `radius` oder `borderRadius` | `border.radius` |
| `borderColor` | `border.color` (Linie `1px solid`) |
| `style` | `styles` |

Prozent- und Pixelwerte in `backgroundSize` (z. B. `"50%"`) gibt es nicht mehr; solche Bilder werden mit `contain` eingepasst. Die Größe stellst du über `width` und `height` ein.

Zwei Dinge sehen jetzt etwas anders aus:

- Hinter einem geladenen Bild ist die Box transparent statt hellgrau. Wer die graue Fläche um ein `contain`-Bild behalten will, setzt `backgroundColor: "#f0f2f6"`.
- Mit `height: "auto"` war die Box bisher leer und null Pixel hoch. Jetzt folgt die Höhe dem Bild.

#### Allgemeine Settings

### uniqueId

Die ***uniqueId*** vergibst du pro Bild eindeutig, z. B. mit der Datensatz-Nummer. Fehlt sie, vergibt das Widget selbst eine ID und schreibt eine Warnung in die Konsole.

```javascript
uniqueId: "ProjektBild" + Nr // Text + Ninox Nr
```

### value

Die Bildquelle: eine URL, ein Ninox-Share-Link oder eine Data-URL. Ohne Wert erscheint der Platzhalter.

```javascript
value: text(Projekt.'Bild URL'),
```

### alt

Textalternative für Screenreader. Ohne `alt` wird `title` verwendet. Bei rein dekorativen Bildern beides weglassen.

```javascript
alt: "Logo der Firma " + Firma.Name,
```

### title

Tooltip beim Überfahren mit der Maus.

```javascript
title: "Logo",
```

### width

Mit ***width*** stellst du die Breite der Box ein. Ohne `width` ist die Box so breit wie das Bild, höchstens so breit wie der Container.

```javascript
width: "100%", // volle Breite
width: "100px", // Pixel-Werte
```

### height

Mit ***height*** stellst du die Höhe der Box ein. Ohne `height` (oder mit `"auto"`) folgt die Höhe dem Bild.

```javascript
height: "auto",
height: "300px",
```

### aspectRatio

Seitenverhältnis der Box. Die Box nimmt die volle Breite (oder `width`), die Höhe folgt dem Verhältnis. Praktisch für Karten, deren Bilder unterschiedliche Formate haben.

```javascript
aspectRatio: "16/9",
aspectRatio: "1", // quadratisch
```

### objectFit

Mit ***objectFit*** bestimmst du, wie das Bild eine Box mit fester Größe füllt.

```javascript
objectFit: "cover", // füllt die Box komplett, schneidet dabei zu
objectFit: "contain", // zeigt das ganze Bild (Standard)
objectFit: "fill", // verzerrt auf die Box
objectFit: "none", // Originalgröße
```

### objectPosition

Welcher Teil sichtbar bleibt, wenn das Bild zugeschnitten wird.

```javascript
objectPosition: "top",
objectPosition: "50% 20%",
```

### backgroundColor

Mit ***backgroundColor*** bestimmst du die Farbe hinter dem Bild, sichtbar um ein `contain`-Bild und hinter transparenten Pixeln. Ohne Wert ist die Box transparent; beim Laden und im Platzhalter ist sie hellgrau.

```javascript
backgroundColor: "#1D8C96",
backgroundColor: "transparent",
```

### initials

Mit ***initials*** zeigst du ein kurzes Kürzel statt des Platzhalter-Icons, solange es kein Bild gibt oder es nicht lädt. Ideal für Profile ohne Foto. Angezeigt werden höchstens drei Zeichen in Großbuchstaben, die Schrift wächst mit der Box. Während das Bild lädt, bleibt die Box grau. Benenne die Person zusätzlich in ***alt***, damit Screenreader den Namen vorlesen.

```javascript
initials: "JJ",
initials: substr(text(Vorname), 0, 1) + substr(text(Nachname), 0, 1),
```

### fontColor

Farbe der ***initials***. Standard: dunkelgrau.

```javascript
fontColor: "#FFFFFF",
```

### border

Linie und Abrundung der Box. Die Linie erscheint, sobald `color`, `width`, `style` oder `sides` gesetzt ist; `radius` allein rundet nur die Ecken.

```javascript
border: { radius: "8px" },
border: { color: "#E4E4E7", width: "1px", radius: "50%" },
```

### loading

Bilder laden erst, wenn sie ins Bild scrollen (`"lazy"`, Standard). Das spart in langen Tabellen viel Ladezeit. `"eager"` lädt sofort.

```javascript
loading: "eager",
```

### styles

Eigene CSS-Deklarationen, die zuletzt auf die Box angewendet werden.

```javascript
styles: "opacity: 0.3;",
```

### Verschachtelt in anderen Widgets

In Layout-Blöcken, Tabellenzellen und anderen Slots kannst du das Bild als Descriptor einsetzen:

```javascript
value: {
    widget: "arc-widget-image",
    uniqueId: "Avatar" + Nr,
    data: {
        value: text(Mitarbeiter.'Foto URL'),
        alt: Mitarbeiter.Name,
        width: "32px",
        height: "32px",
        objectFit: "cover",
        border: { radius: "50%" }
    }
}
```
<!-- /host -->


---

# Input

Source: https://www.arc-rider.com/docs/mini-widgets/input


<!-- host:react -->
# Input in React

Text, Zahlen, Datum oder Uhrzeit erfassen. Der Wert liegt im React-State; `onChange` meldet jede übernommene Änderung.

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

<!-- react-example: input-01-date.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetInput } from '@arcrider/arcwidgets-react';

export default function Example() {
  const [value, setValue] = useState('25.11.1990');
  return (
    <ArcWidgetInput
      data={{
        type: 'date',
        value,
        height: '40px',
        placeholderSettings: {
          value: 'Date',
          fontColor: '#000',
          backgroundColor: '#ccc',
        },
        labelSettings: { title: 'Date' },
      }}
      onChange={(next) => setValue(String(next ?? ''))}
    />
  );
}
```

## Features ausprobieren

### Numpad, Bestätigen und Zurücksetzen

Fokussiere das Feld, um den Numpad zu öffnen. Bestätigen löst `onActions` mit `source: 'submit'` aus; der Reset-Button leert den Wert und meldet `source: 'reset'`.

<!-- react-example: input-06-number_numpad.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetInput } from '@arcrider/arcwidgets-react';

type Props = { onSubmit?: (value: string) => void };

export default function Example({ onSubmit }: Props) {
  const [value, setValue] = useState<string | number>('');
  return (
    <ArcWidgetInput
      data={{
        type: 'number',
        value,
        width: '180px',
        height: '40px',
        alignX: 'right',
        numberFormat: {
          digits: 2,
          decimalSeparator: ',',
          thousandSeparator: '.',
        },
        numpad: {
          enabled: true,
          allowNegative: false,
          maxDecimals: 2,
          suffix: '€',
          openOnFocus: true,
        },
        reset: { visible: true, value: null },
        placeholderSettings: {
          value: 'Enter amount',
          fontColor: '#999',
          backgroundColor: '#fff',
        },
        labelSettings: { title: 'Amount (€)' },
      }}
      onChange={(next) => setValue(next ?? '')}
      onActions={(next, source) => {
        if (source === 'submit') onSubmit?.(next);
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

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

Feuert, wenn sich der übernommene Wert ändert (Blur, Enter, Bestätigen im Picker oder Numpad, Reset). Liefert Text bei `text` und `textarea`, eine Zahl bei `number`, Epoch-Millisekunden bei `date`, `'HH:MM'` bei `time`, `null` bei leerem Feld oder nach einem Reset `reset.value`.

```typescript
onChange?: (value: string | number | null) => void | Promise<void>;
```

### onActions

Feuert, wenn die Eingabe bestätigt wird (Enter, Bestätigen im Picker oder Numpad) oder das Feld über den Reset-Button geleert wird. Der Wert ist der übernommene Wert als Text; `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.

### type

Eingabetyp; `textarea` erlaubt mehrere Zeilen. Standard: `text`.

Typ: `'text' | 'number' | 'date' | 'time' | 'textarea'`.

### value

Aktueller Wert: Text, eine Zahl oder ein lokal formatierter Zahlen-String bei `number`, `'DD.MM.YYYY'` oder Epoch-Millisekunden bei `date`, `'HH:MM'` bei `time`.

Typ: `string | number | null`.

### disabled

Deaktiviert Eingabe, Picker und Reset-Button. Standard: `false`.

Typ: `boolean`.

### tempStorage

Hält getippte Änderungen lokal: `onChange` entfällt beim Tippen und beim Reset, `onActions` feuert weiterhin. Auswahl im Picker oder Numpad ruft `onChange` trotzdem auf. Standard: `false`.

Typ: `boolean`.

### width

Breite des Felds. Standard: `100%`.

Typ: `string`.

### height

Höhe des Felds. Standard: `36px`.

Typ: `string`.

### minHeight

Mindesthöhe des Felds, z. B. für eine mitwachsende Textarea.

Typ: `string`.

### maxHeight

Maximale Höhe des Felds; höherer Inhalt scrollt.

Typ: `string`.

### alignX

Horizontale Textausrichtung im Feld. Standard: `left`.

Typ: `'left' | 'center' | 'right'`.

### paddingX

Innerer Abstand links und rechts. Standard: `8px`.

Typ: `string`.

### paddingY

Innerer Abstand oben und unten. Standard: `2px`.

Typ: `string`.

### fontColor

Schriftfarbe.

Typ: `string`.

### fontSize

Schriftgröße als CSS-Wert. Standard: `13px`.

Typ: `string`.

### fontWeight

Schriftstärke. Standard: `400`.

Typ: `string | number`.

### backgroundColor

Hintergrundfarbe. Standard: `#fafafa`.

Typ: `string`.

### borderWidth

Rahmenstärke; wirkt nur zusammen mit `borderColor`. Standard: `1px`.

Typ: `string`.

### borderColor

Rahmenfarbe. Standard: `#00000015`.

Typ: `string`.

### borderRadius

Abrundung der Ecken; formt auch die Picker-, Numpad- und Reset-Buttons im Feld. Standard: `8px`.

Typ: `string`.

### autocomplete

`false` erlaubt das Autofill des Browsers. Standard: `true` (Autofill aus).

Typ: `boolean`.

### selection

Hervorhebung des aktiven Datums- oder Zeitsegments beim Bearbeiten (`backgroundColor`, `borderRadius`, `color`).

Typ: `ArcWidgetInputSelection`.

### focusAction

Breite und Outline des Felds im Fokus (`width`, `showFocusOutline`, `outlineWidth`, `outlineColor`) und wohin der Fokus nach einer übernommenen Änderung wandert (`nextField` mit `loop: 'infinite'`).

Typ: `ArcWidgetInputFocusAction`.

### placeholderSettings

Platzhaltertext (`value`), seine Farbe und der Hintergrund des leeren Felds.

Typ: `ArcWidgetInputPlaceholderSettings`.

### labelSettings

Beschriftung über dem Feld (`title`) mit Schriftgröße, Farbe, Ausrichtung und Abstand.

Typ: `ArcWidgetInputLabelSettings`.

### numberFormat

Dezimalstellen und Trennzeichen für `number`. Standard: `digits: 2`, Dezimal `","`, Tausender `"."`.

Typ: `ArcWidgetInputNumberFormat`.

### numpad

Bildschirmtastatur für `number`, standardmäßig aktiv. `suffix` setzt die Einheit im Feld und im Numpad; `enabled: false` schaltet auf normale Tastatureingabe.

Typ: `ArcWidgetInputNumpad`.

### reset

Reset-Button (X) im Feld, sichtbar mit `visible: true`, solange das Feld einen Wert hat. `value` ist der Wert nach dem Reset (Standard `null`).

Typ: `ArcWidgetInputReset`.

### timeSettings

Zeit-Picker für `time`: `format` (`'24h'` oder `'12h'`), `minuteStep` (Standard `5`), `showNow`, Anpassungen einzelner `hours` und `minutes` sowie Abschnitts-`labels`.

Typ: `ArcWidgetInputTimeSettings`.

### liveUpdate

Übernimmt getippten Text laufend, optional mit Verzögerung (`debounce`, Standard `300` ms), Mindestlänge (`minLength`) und ohne `onActions` (`actions: false`).

Typ: `boolean | ArcWidgetInputLiveUpdate`.

## 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` bleiben getippte Werte lokal im Widget und `onChange` entfällt dafür; nutze das nur bewusst.

- Der Zahlen-Numpad bestätigt über Fertig, Blur oder Enter. `liveUpdate` wirkt dort nicht wie bei Text. Für einen sichtbaren Reset muss `reset.visible` gesetzt sein.

`labelSettings.title` und `reset.icon` akzeptieren Text, HTML-Strings oder Widget-Deskriptoren; übergib dort einfachen Text statt eines JSX-Elements. 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: input -->
```typescript
export interface ArcWidgetInputReset {
	visible?: boolean;
	value?: string | number | null;
	icon?: string | ArcNestedWidgetDescriptor;
	color?: string;
	backgroundColor?: string;
	borderRadius?: string;
}

export interface ArcWidgetInputNumberFormat {
	digits?: number | null;
	decimalSeparator?: string;
	thousandSeparator?: string;
}

export interface ArcWidgetInputNumpad {
	enabled?: boolean;
	size?: 'default' | 'mini';
	openOnFocus?: boolean;
	allowNegative?: boolean;
	maxDecimals?: number;
	suffix?: string;
	clearOnFirstInput?: boolean;
}

export interface ArcWidgetInputPlaceholderSettings {
	value?: string;
	fontColor?: string;
	backgroundColor?: string;
}

export interface ArcWidgetInputLabelSettings {
	title?: string | number | ArcNestedWidgetDescriptor;
	fontSize?: string;
	fontColor?: string;
	alignX?: 'left' | 'center' | 'right';
	gap?: string;
}

export interface ArcWidgetInputFocusAction {
	width?: string;
	showFocusOutline?: boolean;
	outlineWidth?: string;
	outlineColor?: string;
	nextField?: 'this' | (string & {});
	loop?: 'infinite';
}

export interface ArcWidgetInputSelection {
	backgroundColor?: string;
	borderRadius?: string;
	color?: string;
}

export interface ArcWidgetInputTimeOption {
	value: number;
	label?: string | number;
	backgroundColor?: string;
	fontColor?: string;
}

export interface ArcWidgetInputTimeLabels {
	hours?: string;
	minutes?: string;
}

export interface ArcWidgetInputTimeSettings {
	format?: '24h' | '12h';
	minuteStep?: number;
	showNow?: boolean;
	hours?: ArcWidgetInputTimeOption[];
	minutes?: ArcWidgetInputTimeOption[];
	labels?: ArcWidgetInputTimeLabels;
}

export interface ArcWidgetInputLiveUpdate {
	debounce?: number;
	minLength?: number;
	actions?: boolean;
}

export interface ArcWidgetInputData {
	type?: 'text' | 'number' | 'date' | 'time' | 'textarea';
	value?: string | number | null;
	disabled?: boolean;
	tempStorage?: boolean;
	width?: string;
	height?: string;
	minHeight?: string;
	maxHeight?: string;
	alignX?: 'left' | 'center' | 'right';
	paddingX?: string;
	paddingY?: string;
	fontColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
	borderWidth?: string;
	borderColor?: string;
	borderRadius?: string;
	autocomplete?: boolean;
	selection?: ArcWidgetInputSelection;
	focusAction?: ArcWidgetInputFocusAction;
	placeholderSettings?: ArcWidgetInputPlaceholderSettings;
	labelSettings?: ArcWidgetInputLabelSettings;
	numberFormat?: ArcWidgetInputNumberFormat;
	numpad?: ArcWidgetInputNumpad;
	reset?: ArcWidgetInputReset;
	timeSettings?: ArcWidgetInputTimeSettings;
	liveUpdate?: boolean | ArcWidgetInputLiveUpdate;
}

export interface ArcWidgetInputProps extends ArcReactWidgetProps<ArcWidgetInputData> {
	onChange?: (value: string | number | null) => void | Promise<void>;
	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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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

![](https://framerusercontent.com/images/39CfOjKuSZ4PvVFwHAh0IZm7Lc.png)

`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).
<!-- /host -->


---

# 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

![](https://framerusercontent.com/images/8Iufr8Km4medM3pbMqUHXK8sr4.png)

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

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Beschreibung

</th></tr><tr><td>`uniqueId`

</td><td>Text

</td><td>Eindeutige ID für das Pagination-Element. Pflichtfeld.

</td></tr><tr><td>`editable`

</td><td>Boolean

</td><td>Ermöglicht manuelle Eingabe der Seitenzahl im Input-Feld.

</td></tr><tr><td>`recordId`

</td><td>Text

</td><td>ID des aktuellen Datensatzes, auf den das Update erfolgt. (Die Aktion ausgeführt wird)

</td></tr><tr><td>`fieldId`

</td><td>Text

</td><td>Das Feld, das die aktuelle Seite speichert.

</td></tr><tr><td>`direction`

</td><td>Text

</td><td>Layout der Pagination: `"horizontal"` (Standard) oder `"vertical"`.

</td></tr><tr><td>`title`

</td><td>Text

</td><td>Der aktuell angezeigte Wert im Input-Feld.

</td></tr><tr><td>`value`

</td><td>Zahl

</td><td>Aktuelle Seitenzahl – wichtig für Navigation und Bedingung von Buttons.

</td></tr><tr><td>`total`

</td><td>Zahl

</td><td>Gesamtzahl an Seiten (z. B. `ceil(cnt(list) / 30)`).

</td></tr><tr><td>`totalPrefix`

</td><td>Text

</td><td>Kleiner Zusatz vor der Gesamtseitenanzahl, z. B. `" von "`.

</td></tr><tr><td>`valuePrefix`

</td><td>Text

</td><td>Optionaler String, der beim Update vor die Seitenzahl gesetzt wird.

</td></tr><tr><td>`buttonFirst`

</td><td>Widget

</td><td>Optionaler Inhalt (Text oder Widget) für den „erste Seite“-Button.

</td></tr><tr><td>`buttonMinus`

</td><td>Widget

</td><td>Optionaler Inhalt (Text oder Widget) für den „zurück“-Button.

</td></tr><tr><td>`buttonPlus`

</td><td>Widget

</td><td>Optionaler Inhalt (Text oder Widget) für den „vor“-Button.

</td></tr><tr><td>`buttonLast`

</td><td>Widget

</td><td>Optionaler Inhalt (Text oder Widget) für den „letzte Seite“-Button.

</td></tr></tbody></table></figure>## 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


<!-- host:react -->
# 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



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



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

### 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 Fortschrittswert; numerische Strings werden umgewandelt. Standard: `0`.

Typ: `number | string`.

### valueTotal

Zielwert; der Balken bleibt leer, solange er nicht größer als null ist. Standard: `0`.

Typ: `number | string`.

### valueText

Reine Textbeschriftung, fett neben dem Balken; leer wird sie ausgeblendet.

Typ: `string | number`.

### progressColor

Farbe des gefüllten Bereichs. Ohne Angabe ist sie unter 100 % bernsteinfarben, bei genau 100 % grün und über 100 % schwarz.

Typ: `string`.

### backgroundColor

Farbe des Balkens. Standard: `rgba(0,0,0,0.25)`.

Typ: `string`.

### width

Breite des Balkens. Standard: `100%`.

Typ: `string`.

### height

Höhe des Balkens. Standard: `10px`.

Typ: `string`.

### borderRadius

Abrundung der Ecken des Balkens. Standard: `50px`.

Typ: `string`.

### fontColor

Farbe der Beschriftung. Standard: `#000000`.

Typ: `string`.

### fontSize

Schriftgröße der Beschriftung. Standard: `12px`.

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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: progress_bar -->
```typescript
export interface ArcWidgetProgressBarData {
	valueProgress?: number | string;
	valueTotal?: number | string;
	valueText?: string | number;
	progressColor?: string;
	backgroundColor?: string;
	width?: string;
	height?: string;
	borderRadius?: string;
	fontColor?: string;
	fontSize?: string;
}

export interface ArcWidgetProgressBarProps extends ArcReactWidgetProps<ArcWidgetProgressBarData> {}
```

## 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)
<!-- /host -->

<!-- host:ninox,vue -->
# 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

![](https://framerusercontent.com/images/CvZw4Szz9DlFWKAz2ei35byiyk.png)

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
    })
```
<!-- /host -->


---

# Select (Dropdown)

Source: https://www.arc-rider.com/docs/mini-widgets/select


<!-- host:react -->
# 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

<!-- react-example: select-01-chrome.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetSelect } from '@arcrider/arcwidgets-react';

const items = [
  { title: 'Open', value: 'open' },
  { title: 'In progress', value: 'work' },
  { title: 'Done', value: 'done' },
];

export default function Example() {
  const [value, setValue] = useState<string | number | null>(null);
  return (
    <ArcWidgetSelect
      data={{
        placeholder: 'Choose status',
        width: '240px',
        items: items.map((item) => ({ ...item, active: item.value === value })),
      }}
      onChange={setValue}
    />
  );
}
```

## Features ausprobieren

### Auswahl, Zurücksetzen und deaktivierter Zustand

Wähle einen Status und prüfe das separate Badge mit derselben Auswahl. Teste anschließend die leere und deaktivierte Variante.

<!-- react-example: select-02-overview.tsx -->
```tsx
import {
  ArcWidgetLayout,
  ArcWidgetSelect,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

const cards = [
  {
    label: 'Status (colored)',
    data: {
      width: '260px',
      height: '40px',
      borderRadius: '8px',
      borderColor: '#16A34A',
      borderWidth: '2px',
      backgroundColor: '#DCFCE7',
      fontColor: '#166534',
      fontSize: '14px',
      fontWeight: '600',
      currentValue: 'In progress',
      placeholder: 'Choose status',
      reset: { title: 'Reset', value: '' },
      items: [
        { title: 'Open', value: '1' },
        { title: 'In progress', value: '2', active: true },
        { title: 'Done', value: '3' },
        { title: 'Cancelled', value: '4' },
      ],
    },
  },
  {
    label: 'Filter (pill)',
    data: {
      width: '220px',
      height: '36px',
      borderRadius: '999px',
      backgroundColor: '#F1F5F9',
      borderColor: '#E2E8F0',
      fontSize: '13px',
      fontWeight: '600',
      fontColor: '#334155',
      placeholder: 'Show all',
      currentValue: 'Active only',
      reset: { title: 'Show all', value: '' },
      items: [
        { title: 'Show all', value: '' },
        { title: 'Active only', value: 'active', active: true },
        { title: 'Inactive only', value: 'inactive' },
        { title: 'Archived', value: 'archived' },
      ],
    },
  },
  {
    label: 'Dark theme',
    data: {
      width: '260px',
      height: '44px',
      borderRadius: '8px',
      backgroundColor: '#1E293B',
      borderColor: '#334155',
      borderWidth: '1px',
      fontColor: '#F1F5F9',
      fontSize: '14px',
      fontWeight: '500',
      placeholder: 'Choose theme',
      currentValue: 'Dark Mode',
      itemsSettings: {
        backgroundColor: '#1E293B',
        borderColor: '#334155',
        fontColor: '#F1F5F9',
        hoverBackgroundColor: '#334155',
        activeBackgroundColor: '#293548',
        iconColor: '#94A3B8',
        selectedIconColor: '#F1F5F9',
      },
      items: [
        { title: 'Light Mode', value: '1' },
        { title: 'Dark Mode', value: '2', active: true },
        { title: 'System', value: '3' },
      ],
    },
  },
  {
    label: 'Compact (for tables)',
    data: {
      width: '160px',
      height: '30px',
      borderRadius: '4px',
      fontSize: '12px',
      placeholder: 'Select',
      currentValue: 'Medium',
      items: [
        { title: 'Low', value: '1' },
        { title: 'Medium', value: '2', active: true },
        { title: 'High', value: '3' },
        { title: 'Critical', value: '4' },
      ],
    },
  },
  {
    label: 'Multi-select',
    data: {
      multiselect: true,
      width: '300px',
      borderRadius: '6px',
      fontSize: '14px',
      placeholder: 'Select...',
      currentValue: 'Item 1, Item 3',
      items: [
        { title: 'Item 1', value: '1', active: true },
        { title: 'Item 2', value: '2' },
        { title: 'Item 3', value: '3', active: true },
        { title: 'Item 4', value: '4' },
        { title: 'Item 5', value: '5' },
      ],
    },
  },
  {
    label: 'Disabled',
    data: {
      disabled: true,
      width: '260px',
      height: '40px',
      borderRadius: '6px',
      fontSize: '14px',
      placeholder: 'Select',
      currentValue: 'Read only',
      items: [
        { title: 'Option 1', value: '1', active: true },
        { title: 'Option 2', value: '2' },
      ],
    },
  },
];

const card = ({ label, data }: (typeof cards)[number]) => ({
  width: 'fraction' as const,
  alignY: 'stretch' as const,
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        height: '100%',
        gap: '12px',
        paddingX: '20px',
        paddingY: '24px',
        backgroundColor: '#FFFFFF',
        border: { color: '#EBEDF5', radius: '12px' },
        blocks: [
          { width: 'auto', value: <ArcWidgetSelect data={data} /> },
          {
            width: 'auto',
            value: (
              <ArcWidgetText
                data={{
                  value: label.toUpperCase(),
                  width: 'auto',
                  fontSize: '11px',
                  fontWeight: '600',
                  fontColor: '#64748B',
                }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

// Two cards per row, each taking half the width.
const rows = [cards.slice(0, 2), cards.slice(2, 4), cards.slice(4)];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'left',
        alignY: 'top',
        height: 'auto',
        gap: '24px',
        paddingX: '32px',
        paddingY: '32px',
        backgroundColor: '#F8FAFC',
        blocks: rows.map((row) => ({
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'horizontal',
                alignX: 'left',
                alignY: 'stretch',
                height: 'auto',
                gap: '24px',
                blocks: row.map(card),
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

### data

Konfiguration vom Typ `ArcWidgetSelectData`. Ü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

Feuert beim Klick auf eine Option mit deren `value`, beim Reset-Eintrag mit `reset.value` (oder `null`).

```typescript
onChange?: (value: string | number | null) => void;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### items

Optionen der Liste (`title`, `icon`, `value`, `active`); siehe den zugehörigen Datentyp.

Typ: `ArcWidgetSelectItem[]`.

### currentValue

Inhalt im geschlossenen Feld: Text, HTML-String oder Widget-Deskriptor.

Typ: `string | number | ArcNestedWidgetDescriptor`.

### placeholder

Text, der bei leerem `currentValue` und im Filterfeld erscheint.

Typ: `string`.

### multiselect

Hält die Liste nach einem Klick offen, damit mehrere Optionen gewählt werden können; der Callback liefert pro Klick einen Einzelwert. Standard: `false`.

Typ: `boolean`.

### disabled

Verhindert das Öffnen der Liste. Standard: `false`.

Typ: `boolean`.

### clickPosition

`'icon'` öffnet die Liste nur über das Icon; standardmäßig öffnet das ganze Feld sie.

Typ: `'icon'`.

### icon

Icon am Ende des Felds als SVG- oder HTML-String oder als Widget-Deskriptor. Standard: ein Chevron.

Typ: `string | ArcNestedWidgetDescriptor`.

### width

Breite des Felds. Standard: `100%`.

Typ: `string`.

### flex

CSS-`flex` des Widgets, z. B. `'1'`, um den restlichen Platz einer Zeile zu füllen.

Typ: `string`.

### height

Höhe des Felds. Standard: `36px`.

Typ: `string`.

### alignX

Horizontale Ausrichtung von `currentValue` im Feld. Standard: `left`.

Typ: `'left' | 'center' | 'right'`.

### fontColor

Text- und Iconfarbe des Felds. Standard: `inherit`.

Typ: `string`.

### fontSize

Schriftgröße als CSS-Wert. Standard: `13px`.

Typ: `string`.

### fontWeight

Schriftstärke. Standard: `400`.

Typ: `string | number`.

### backgroundColor

Hintergrundfarbe. Standard: `#fafafa`.

Typ: `string`.

### borderColor

Rahmenfarbe. Standard: `#00000015`.

Typ: `string`.

### borderWidth

Rahmenstärke. Standard: `1px`.

Typ: `string`.

### borderRadius

Abrundung der Ecken. Standard: `8px`.

Typ: `string`.

### labelSettings

Beschriftung über dem Feld (`title`) mit Ausrichtung, Höhe, Schriftgröße, Farbe und Abstand.

Typ: `ArcWidgetSelectLabelSettings`.

### itemsSettings

Darstellung der Optionsliste: `width` (Standard: Feldbreite), `height`, Radien, Farben und das Häkchen ausgewählter Optionen.

Typ: `ArcWidgetSelectItemsSettings`.

### reset

Reset-Eintrag oben in der Liste. `title` setzt die Beschriftung, `hide: true` entfernt ihn, `value` geht an `onChange` (leere Werte werden zu `null`).

Typ: `ArcWidgetSelectReset`.

### focusAction

Verhalten beim Öffnen: `autoFocus` fokussiert das Filterfeld (Standard `true`), `showCurrentValue` lässt `currentValue` daneben sichtbar.

Typ: `ArcWidgetSelectFocusAction`.

## Verhalten und Grenzen

- `items[].value` ist der Callback-Wert. `currentValue` ist die sichtbare Beschriftung; `items[].active` markiert die Auswahl. Halte alle drei aus demselben State aktuell.

- `multiselect: true` hält die Liste offen. Der Callback liefert weiterhin den einzelnen angeklickten Wert; Hinzufügen oder Entfernen aus einer Auswahlmenge implementierst du selbst.

- Reset liefert `null`, sofern `reset.value` nicht gesetzt ist. Behandle diesen Fall ausdrücklich.

- Der Reset-Eintrag erscheint standardmäßig mit der Beschriftung `(leer)`. Setze `reset.title` oder `reset.hide: true`.

Verwende Text für die Optionsbeschriftungen. JSX-Elemente und Widget-Deskriptoren werden im Dropdown nicht unterstützt. Das Live-Beispiel zeigt ein separates Badge aus demselben Auswahl-State. 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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: select -->
```typescript
export interface ArcWidgetSelectItem {
	title?: string | number;
	icon?: string;
	active?: boolean;
	value?: string | number;
}

export interface ArcWidgetSelectReset {
	hide?: boolean;
	title?: string;
	icon?: string;
	value?: string | number;
}

export interface ArcWidgetSelectItemsSettings {
	width?: string;
	height?: string;
	borderRadius?: string;
	itemBorderRadius?: string;
	backgroundColor?: string;
	borderColor?: string;
	fontColor?: string;
	hoverBackgroundColor?: string;
	activeBackgroundColor?: string;
	iconColor?: string;
	selectedIconColor?: string;
	showSelectedIcon?: boolean;
	selectedIcon?: string | false;
}

export interface ArcWidgetSelectLabelSettings {
	title?: string | number | ArcNestedWidgetDescriptor;
	alignX?: 'left' | 'center' | 'right';
	height?: string;
	fontSize?: string;
	fontColor?: string;
	gap?: string;
}

export interface ArcWidgetSelectFocusAction {
	autoFocus?: boolean;
	showCurrentValue?: boolean;
}

export interface ArcWidgetSelectData {
	items?: ArcWidgetSelectItem[];
	currentValue?: string | number | ArcNestedWidgetDescriptor;
	placeholder?: string;
	multiselect?: boolean;
	disabled?: boolean;
	clickPosition?: 'icon';
	icon?: string | ArcNestedWidgetDescriptor;
	width?: string;
	flex?: string;
	height?: string;
	alignX?: 'left' | 'center' | 'right';
	fontColor?: string;
	fontSize?: string;
	fontWeight?: string | number;
	backgroundColor?: string;
	borderWidth?: string;
	borderColor?: string;
	borderRadius?: string;
	labelSettings?: ArcWidgetSelectLabelSettings;
	itemsSettings?: ArcWidgetSelectItemsSettings;
	reset?: ArcWidgetSelectReset;
	focusAction?: ArcWidgetSelectFocusAction;
}

export interface ArcWidgetSelectProps extends ArcReactWidgetProps<ArcWidgetSelectData> {
	onChange?: (value: string | number | null) => 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)
<!-- /host -->

<!-- host:ninox,vue -->
# Select (Dropdown)

## AI Defaults (read first)

- **uniqueId**: Required, e.g. `"select-status-" + Nr`.
- **recordId**: Required for Ninox data 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` also works). Adapter-only.
- **items**: Use `(select Table).[{ title: ..., active: ..., value: number(Nr) }]` – `value` MUST be `number(Nr)`.
- **focusAction**: Set `{ autoFocus: false }` (important on tablets).
- **reset**: `{ title: "Alle", value: "", hide: true }` to add a reset option.
- **Persistence**: Selection emits semantic `change` with the item `value`; Ninox adapter writes `type: "update"`. React: `onChange(value)` / `onAction('change', value)`.
- **Nested widgets**: `currentValue`, `icon`, and `items[].title` (and reset row `title`) may use `arcCustomIcon`, `arcCustomBadge`, `arcCustomButton`, or other formula widgets – not only plain text.
- **Null handling**: Do NOT use `else "" end` for empty states.

# Select (Dropdown)

Das Widget `arcCustomSelect` ist dein Tool für moderne, stilvolle Dropdowns in Ninox. Es ersetzt das klassische Auswahlfeld durch ein vollständig anpassbares Interface – mit Icons, Hovereffekten, Tastatursteuerung und dynamischen Einträgen.

![](https://framerusercontent.com/images/sIAp1XmRalt9U4EHtgmp9IyYHuw.png)

Du verwendest `arcCustomSelect` überall dort, wo du deinen Nutzern eine Auswahlmöglichkeit anbieten möchtest – sei es zur Statusvergabe, zum Filtern, oder zur Bearbeitung von Datenfeldern. Das Widget eignet sich ideal für:

- Auswahl von Statuswerten (z. B. „Offen“, „In Bearbeitung“, „Abgeschlossen“)
- Schnelles Tagging oder Labeling von Datensätzen
- Kompakte Navigation innerhalb von Masken
- Filterung in Kombination mit anderen Widgets

📢 Der große Vorteil: Du kannst das Design flexibel anpassen (z. B. Breite, Farben, Schriftgröße), dynamische Item-Listen aus Tabellen befüllen und sogar das Verhalten bei Fokus oder Klick feinsteuern.

<iframe src="https://www.youtube.com/embed/m0cK03sx7SE?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## Gesamter Anwendungscode


```javascript
arcCustomSelect({
    uniqueId: "Status" + Nr,
    recordId: Nr,
    field: "",
    embedded: true,
    width: "",
    height: "",
    alignX: "",
    fontColor: "",
    fontSize: "",
    fontWeight: "",
    backgroundColor: "",
    borderColor: "",
    borderWidth: "",
    borderRadius: "",
    itemsSettings: {
            width: "",
            height: "",
            borderRadius: ""
        },
    labelSettings: {
            title: "",
            fontSize: "",
            alignX: "",
            height: ""
    },
    clickPosition: "",
    placeholder: "",
    disabled: false,
    multiselect: false,
    reset: {
            title: "",
            value: "",
            hide: true
        },
  focusAction: {
    autoFocus: false,
    showCurrentValue: false
        },
    currentValue: text(Status),
    items: let id := Nr;
        (select Status).[{
            title: Titel,
            active: number(id.Status) = number(Nr),
            value: number(Nr)
            }]
})
```

## Einzelne Parameter

### uniqueId

Pflichtfeld: ✅

Mit `uniqueId` wird jede Select-Instanz eindeutig identifizierbar – besonders wichtig, wenn **mehrere Custom Selects** gleichzeitig auf der Seite verwendet werden.

Die ID sorgt intern dafür, dass:

- **Fokus, Auswahl und Tastaturverhalten** korrekt zugeordnet werden,
- keine Überschneidungen zwischen Instanzen auftreten,
- der Zustand jeder Select-Box stabil bleibt, auch bei schnellem Wechsel oder dynamischem Nachladen.


```javascript
uniqueId: Nr, // Ninox-Feld
uniqueId: "Aufgabe Beschreibung", // Text in "
```

### recordId

Pflichtfeld: ✅

Der Parameter `recordId` verknüpft die Select-Komponente mit einem konkreten Datensatz in Ninox – und zwar genau dem, in dem sich das Feld befindet, das du mit dem Select-Widget bespielen möchtest.


```javascript
recordId: Nr, // Ninox-Tabellen Id
```

### field

Pflichtfeld: ✅

Der Parameter `field` gibt an, welches Feld im angegebenen Datensatz (`recordId`) vom Select-Widget gelesen und beschrieben werden soll.

Dabei handelt es sich nicht um den sichtbaren Feldnamen, sondern um die interne `fieldId` des Feldes in Ninox**.**

**🔍 So findest du die fieldId**

Die `fieldId` ist eine systeminterne Bezeichnung, z. B. `"K4"`.

Du kannst sie auf zwei Arten ermitteln:

- Mit der Ninox-Funktion: `fieldId()`
- Oder mit dem kostenlosen Mini-Widget:  `fieldFinder`


```javascript
field: "B1",
field: fieldId(Nr, "Status")
field: "", // gibst du keine Id an, funktioniert das Select nicht
```

### embedded

Gibt an, ob das Select-Widget **innerhalb eines anderen Widgets eingebettet** ist – z. B. innerhalb einer [Custom Table](/custom-table)-Spalte oder eines [Layout](https://www.arc-rider.de/en/documentation/custom-layout)-Containers – oder ob es **frei in einem Ninox-Formular als eigenständiges Widget** eingebunden wird (z. B. direkt in einem Formelfeld).


```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // wenn Text eingebettet in anderes Widget
embedded: "", // default: true
```

### width

Der Parameter `width` steuert die Darstellungsbreite des Select-Widgets. Du kannst entweder eine feste Breite in Pixeln angeben, z. B. `"240px"`, oder eine relative Breite wie `"100%"`, damit sich das Widget flexibel an das umgebende Layout anpasst.

**Anwendung**

- In frei platzierten Formelfeldern kannst du mit `width` gezielt das Layout beeinflussen.
- Wird das Widget eingebettet verwendet (z. B. in einer [CustomTable](https://www.arc-rider.de/en/documentation/custom-table)-Spalte), kannst du die Breite automatisch an das Eltern-Element anpassen, wenn du die `width: 100% `einstellst.

💡 **Empfehlung**: Vermeide sehr kleine Breiten – lange Platzhalter oder Auswahlwerte könnten sonst abgeschnitten dargestellt werden.


```javascript
width: "100%", // Prozent-Werte oder "80px" Pixel-Werte
width: "auto", // width passt sich an Inhalt an
width: "", // default: 100%
```

### height

Mit dem Parameter `height` kannst du die **sichtbare Höhe der Select-Komponente** steuern. Das ist besonders nützlich, wenn du ein einheitliches Layout brauchst oder die Darstellung in Tabellen und verschachtelten Layouts kontrollieren möchtest.


```javascript
height: "100%", // Prozent-Werte oder "80px" Pixel-Werte
height: "auto", // height passt sich automatisch an Inhalt an
height: "", // default: auto
```

### alignX

Mit `alignX` bestimmst du die **horizontale Ausrichtung** des sichtbaren Inhalts im Select-Feld – also zum Beispiel, ob der ausgewählte Wert linksbündig, zentriert oder rechtsbündig dargestellt wird.

**Anwendung**

- `"left"` ist der Standardwert und eignet sich in den meisten Fällen.
- `"center"` kann in sehr schmalen Feldern oder bei rein ikonischen Inhalten sinnvoll sein.
- `"right"` wird selten verwendet, kann aber bei Zahlen oder bestimmten Layoutvorgaben hilfreich sein.

**💡 Empfehlung**: Verwende `center` oder `right` nur, wenn das restliche Layout es verlangt – bei längeren Texten ist `left` in der Regel besser lesbar.


```javascript
alignX: "left", // linksbündig
alignX: "center", // zentriert
alignX: "right", // rechtsbündig
alignX: "", // default:  left
```

### itemsWidth

Mit `itemsWidth` legst du die **Breite der Dropdown-Liste** fest – also des Bereichs, in dem die Auswahloptionen angezeigt werden. Wenn du diesen Wert nicht setzt, richtet sich die Breite der Liste automatisch nach der Breite des Select-Feldes.

**Anwendung: **Du kannst die Dropdown-Liste bewusst breiter oder schmaler machen als das Select-Feld selbst. Das ist besonders hilfreich, wenn die Optionsinhalte länger sind als die Breite des eigentlichen Felds zulässt.


```javascript
itemsWith: "100%", // Prozent-Werte oder "80px" Pixel-Werte
itemsWith: "auto", // width passt sich an Inhalt an
itemsWith: "", // default: 100%
```

### itemsHeight

Der Parameter `itemsHeight` legt die **Höhe einzelner Einträge in der Dropdown-Liste** fest. Damit kannst du steuern, wie viel Platz jeder Auswahlpunkt einnimmt – unabhängig von der Schriftgröße.


```javascript
itemsHeight: "100%", // Prozent-Werte oder "80px" Pixel-Werte
itemsHeight: "auto", // height passt sich an
itemsHeight: "", // default: auto
```

### fontColor

Mit `fontColor` kannst du die **Schriftfarbe der Auswahlanzeige im Select-Feld** festlegen. Das betrifft sowohl Platzhaltertext als auch den aktuell ausgewählten Wert.

**💡 Empfehlung: **Verwende möglichst hohe Kontraste zum Hintergrund – insbesondere bei eingebetteten Varianten in farbigen Layouts. Bei dunklem Hintergrund solltest du eine helle Schriftfarbe wählen, z. B. `"#ffffff"`.


```javascript
fontColor: "#EEEEEE", // z.B. HEX-Wert in "
fontColor: "", // default: #000
```

### fontSize

Der Parameter `fontSize` bestimmt die **Größe des Textes innerhalb des Select-Feldes** – also sowohl für Platzhalter als auch für ausgewählte Einträge.


```javascript
fontSize: "15px",
fontSize: "", // default: 13px
```

### fontWeight

Der Parameter `fontWeight` bestimmt die **Schriftstärke** des Textes im Select-Feld (values & placeholder). Damit kannst du gezielt steuern, ob der Text eher dezent oder betont dargestellt werden soll.

**Anwendung: **Du kannst zwischen vordefinierten Werten wie `"normal"` oder `"bold"` wählen oder numerische Gewichtungen wie `400` (normal) oder `600` (halbfett) verwenden. Das ist besonders nützlich, wenn du verschiedene Schriftstärken im Layout systematisch verwendest.


```javascript
fontWeight: "700",
fontWeight: "", // default: 400
```

### backgroundColor

Der Parameter `backgroundColor` legt die **Hintergrundfarbe des sichtbaren Select-Feldes** fest – also die Fläche, in der der Platzhalter oder der ausgewählte Wert angezeigt wird.

**Anwendung: **Du kannst damit das Widget visuell an deine Oberfläche anpassen, z. B. in dunklen Layouts oder bei farblich abgestimmten Eingabefeldern. Unterstützt werden Farbwerte im HEX-Format, RGB oder Klartextnamen wie `"white"` oder `"transparent"`.

**💡 Empfehlung: **Achte auf ausreichenden Kontrast zur Schriftfarbe (`fontColor`), damit der Text gut lesbar bleibt. In dunklen Layouts kann `"transparent"` sinnvoll sein, wenn das Hintergrunddesign durchscheinen soll.


```javascript
backgroundColor: "#4970ff", // z.B. HEX-Wert in "
backgroundColor: "", // default: #FFFFFF
```

### borderColor

Mit dem Parameter `borderColor` legst du die Farbe des Rahmens rund um das Select-Feld fest. Dadurch kannst du das Widget gezielt an dein Farbschema oder Layout anpassen.

**💡 Empfehlung: **Verwende kontrastreiche Rahmenfarben nur gezielt – z. B. um Felder hervorzuheben oder Gruppen optisch zu trennen. Dezente Grautöne wie `"#dddddd"` oder `"#999999"` wirken meist angenehm zurückhaltend.


```javascript
borderColor: "#EEEEEE", // z.B. HEX-Wert in "
borderColor: "", // default: #e5e5e5
```

### borderWidth

Mit `borderWidth` bestimmst du die Dicke des Rahmens rund um das Select-Feld. Dadurch kannst du die visuelle Präsenz des Widgets im Layout erhöhen oder bewusst reduzieren.

**Anwendung: **Setze dünne Rahmen (`"1px"`) für eine dezente Integration oder dickere (`"2px"` bis `"3px"`) für optische Hervorhebung. `"0px"` entfernt den Rahmen komplett, besonders nützlich bei eingebetteten Designs mit klaren Flächen.


```javascript
borderWidth: "#EEEEEE", // z.B. HEX-Wert in "
borderWidth: "", // default: 1px
```

### borderRadius

Der Parameter `borderRadius` steuert die **Abrundung der Ecken** des Select-Feldes. Damit kannst du das Erscheinungsbild der Komponente zwischen eckig, leicht abgerundet oder komplett rund gestalten.

**🧩 Typische Werte**

- `"0px"` → komplett eckig
- `"4px"` → leicht abgerundet (Standard)
- `"6px"` → modern und weich
- `"50%"` → rund (nur sinnvoll bei quadratischer Breite/Höhe)


```javascript
borderRadius: "20px", // z.B. Wert in px
borderRadius: "", // default: 3px
```

### itemsSettings Block

Mit `itemsSettings` kannst du das Erscheinungsbild des gesamten Dropdown-Menüs steuern – nicht einzelner Listeneinträge, sondern des gesamten Bereichs, in dem alle Optionen angezeigt werden.


```javascript
itemsSettings: {
            width: "", // default: 100%
            height: "", // default: 200px
            borderRadius: "" // default:  5px
        },

Einzelerklärungen:

  width: "40px", // Wert in px oder aber auch z.B. "auto"
  width: "", // default: 100%

  height: "200px", // Wert in px oder aber auch z.B. "auto" (passt sich Inhalt an)
  height: "", // default: 200px

  borderRadius: "30px", // Wert in px oder aber auch z.B. "auto" (passt sich Inhalt an)
  borderRadius: "" // default:  3px
```

### labelSettings Block

Mit `labelSettings` steuerst du die Darstellung eines optionalen **Labels über dem Select-Feld** – also einen kurzen Titel oder Hinweistext wie z. B. „Status“ oder „Kategorie“. Dieser Text erscheint oberhalb des Widgets.

- `title` – Der Text, der als Label angezeigt wird (z. B. `"Kategorie"`) — auch als Mini-Widget (z. B. `arcCustomText`)
- `fontSize` – Schriftgröße des Labels (z. B. `"11px"`)
- `fontColor` – Schriftfarbe des Labels (Hex, z. B. `"#EEEEEE"`)
- `alignX` – Horizontale Ausrichtung des Labels (`"left"`, `"center"`, `"right"`)
- `height` – Höhe des Label-Containers (z. B. `"15px"`)


```javascript
labelSettings: {
        title: "",
        fontSize: "",
        alignX: "",
        height: ""
    }

Einzelerklärungen:

  title: "Status", // Wort, in " welches als Label ausgegeben werden soll
  title: "", // kein Label wird angezeigt

  fontSize: "30px", // z.B. Pixel Werte
  fontSize: "", // default: 11px

  alignX: "right", // Label ist rechtsbündig
  alignX: "left", // Label ist linksbündig
  alignX: "", // default: left

  height: "40px", // z.B. Pixel Werte
  height: "", // default: 15px
```

**💡 Hinweise**

- Wird `title` nicht gesetzt oder leer gelassen, erscheint **kein Label**.
- Die Ausrichtung (`alignX`) betrifft nur das Label, nicht das Select-Feld selbst.
- `fontSize` und `height` helfen bei der exakten Abstimmung mit anderen Feldern im Layout.

### clickPosition

Der Parameter `clickPosition` legt fest, **welcher Teil des Select-Feldes klickbar ist**, um das Dropdown-Menü zu öffnen.

**🧩 Mögliche Einstellungen**

- `"icon"` – Nur das kleine Pfeilsymbol ganz rechts ist klickbar.
- `"field"` – Das gesamte Feld (inklusive Textfläche und Icon) ist klickbar. (Standard)


```javascript
clickPosition: "icon", // nur auf icon klickbar (select klappt sich aus)
clickPosition: "", // default: klick auf gesamtem select möglich
```

### placeholder

Der Parameter `placeholder` definiert den **Anzeigetext im Select-Feld**, solange noch **kein Wert ausgewählt wurde**. Er dient als Hinweis für den Nutzer, was im Feld erwartet wird oder welche Auswahl getroffen werden kann.

**🧩 Typische Anwendungsbeispiele**

- `"Bitte auswählen"`
- `"Status wählen"`
- `"–"`


```javascript
placeholder: "select", // eigener Platzhalter
placeholder: "", // default: "Auswählen"
```

Wird ein `placeholder` gesetzt, erscheint er **grau und leicht transparent**, bis eine echte Auswahl getroffen wurde.

**💡 Hinweise**

- Der Text wird **nicht gespeichert**, sondern dient nur zur Anzeige.
- Ist bereits ein `currentValue` übergeben, wird der `placeholder` nicht angezeigt.
- Halte den Text kurz – z. B. `"select"` oder `"choose"` – besonders in schmalen Feldern.

### disabled

Der Parameter `disabled` legt fest, ob das Select-Feld **deaktiviert** ist – also **nicht klickbar** und **nicht bearbeitbar**.

**🧩 Verhalten im deaktivierten Zustand**

- Das Dropdown lässt sich nicht öffnen.
- Der Mauszeiger zeigt Icon "prohibit"  (Kreis mit diagonalem Strich)
- Der aktuelle Wert bleibt sichtbar, kann aber nicht verändert werden.
- Optisch wird das Feld leicht abgeblendet dargestellt.


```javascript
disabled: true, // das select kann nich angeklickt werden
disabled: if Datum < today() then true else false, // hier können eigene Abhängigkeiten definiert werden, wenn bei einer Bestimmten Bedingung das select nicht klickbar sein soll
disabled: "", // default: false (das select ist anklickbar)
```

### multiselect

Der Parameter `multiselect` aktiviert den **Mehrfachauswahl-Modus** im Select-Feld. Damit können **mehrere Werte gleichzeitig** ausgewählt und in das Feld geschrieben werden – statt nur ein einzelner.

**🧩 Verhalten bei aktivem **`**multiselect: true**`

- Jeder Klick auf einen Eintrag fügt den Wert zur Liste hinzu (anstatt ihn zu ersetzen).
- Bereits ausgewählte Werte bleiben erhalten.
- Einträge können visuell als „aktiv“ markiert sein.
- Die Auswahl bleibt auch nach einem Klick geöffnet, damit mehrere Werte direkt nacheinander gewählt werden können.
- Die **Tastatursteuerung** unterscheidet sich leicht:</p><ul><li data-preset-tag="p"><p>`Enter` bestätigt eine Auswahl, das Menü bleibt offen.
- `Tab` wechselt direkt zum nächsten Feld, ohne automatisch zu bestätigen.

</li></ul>
```javascript
multiselect: true // wenn du das Select als Multi-Select nutzen möchtest
multiselect: "" // default: false
```

**⚠️ Wichtig bei der Umsetzung in Ninox**

In Ninox kann ein `multiselect` nicht direkt in ein **Mehrfachauswahlfeld** oder **Mehrfach-Referenzfeld** schreiben. Du musst stattdessen ein **Hilfsfeld vom Typ Text** verwenden:

- Übergib dieses Hilfsfeld im Parameter `field` (bzw. `fieldId`) an das Select-Widget.
- Dort wird der **Text aller ausgewählten Werte (z. B. IDs oder Namen)** gesammelt – meist als kommaseparierte Liste.
- Nutze anschließend einen** „Trigger nach Änderung“** auf das Hilfsfeld, um die tatsächliche Mehrfachauswahl zu befüllen.

**Trigger-Code:**


```javascript
let current := this;
if number(addAuftragsart) = 0 then
    Auftragsart := null
else
    if contains(numbers(current.Auftragsart), number(addAuftragsart)) then
        let value := unique(for item in numbers(current.Auftragsart) do
                    if number(item) = number(addAuftragsart) then
                        0
                    else
                        item
                    end
                end);
        Auftragsart := value[!= 0]
    else
        Auftragsart := unique(numbers(current.Auftragsart), number(addAuftragsart))
    end
end;
addAuftragsart := null
```

### emptyValue

In dem Parameter ***emptyValue*** bestimmst du, was der Text des zurücksetzen Buttons (erstes Auswahlfeld im geöffneten dropdown/items) sein soll.(seit v1.1.0) (wird überschrieben, wenn im reset Block bei title etwas eingetragen ist)

<blockquote>*!! Vorerst bleibt der bisherige Einstellungs-Parameter *`*emptyValue: "zurücksetzen"*`*noch aktiv, nutzt aber bitte in Zukunft für diese Einstellungen den Parameter *`*title: "zurücksetzen"*`* im reset Block.*

</blockquote>
```javascript
emptyValue: "empty", // eigener Text
emptyValue: "", // default: "(leer)")

```

### reset Block

Der `reset`-Block steuert, ob und wie im Dropdown-Menü eine **„Zurücksetzen“-Option** angezeigt wird, mit der der aktuelle Wert gelöscht oder auf einen definierten Wert zurückgesetzt werden kann.

- `title` – Der angezeigte Text für den Zurücksetzen-Eintrag (z. B. `"(leer)"`, `"Zurücksetzen"`).
- `value` – Der Wert, der gesetzt wird, wenn der Eintrag angeklickt wird. Wenn nicht gesetzt, wird automatisch `emptyValue` verwendet.
- `hide` – Wenn `true`, wird der Reset-Eintrag **nicht angezeigt**, kann aber trotzdem intern genutzt werden.


```javascript
reset: {
            title: "reset",
            value: 0,
            hide: true
        },

Einzelerklärungen:

  title: "reset", // eigener Text
  title: "", // default: Wert in Parameter emptyValue (falls emptyValue: " dann ist hier default: "(leer)")

  value: 0, // eigener Wert (0 = setzt den Wert auf 0 statt null zurück)
  value: "", // default: null (Ninox-Feld wird null gesetzt)

  hide: true, // select kann nicht zurückgesetzt werden
  hide: "", // default: false (zurücksetzen Button wird angezeigt)
```

### focusAction Settingsblock

Mit dem Settingsblock `focusAction` kannst du das Verhalten des Suchfelds im Select steuern.

**Parameter:**

- `autoFocus` – Bestimmt, ob der Cursor automatisch in das Suchfeld springt. Besonders für Tablets, wo die Tastatur sofort aufspringt und den User irritieren könnte, ist das Abschalten hilfreich.
- `showCurrentValue` – Wenn `true`, wird der `currentValue` (z.B. deine selbst gebauten Badges via `arcCustomLayout`) links angezeigt und das Suchfeld daneben. Ideal für Multi-Select mit Tag-Darstellung.


```javascript
focusAction: {
    autoFocus: false, // true or false // default: true
    showCurrentValue: true // true or false // default: false
}
```

**🧩 Typische Anwendung für showCurrentValue:**

Wenn du im `currentValue` eigene Badges/Tags mit `arcCustomLayout` renderst und diese beim Öffnen des Selects weiterhin sichtbar bleiben sollen (mit Suchfeld daneben), setze `showCurrentValue: true`.

### currentValue

Der Parameter `currentValue` legt fest, **welcher Wert im Select-Feld  bei ausgewählten items** sein soll. Er bestimmt also die **Anzeige** des Feldes im geschlossenen Zustand.

**🧩 Verhalten je nach Modus**

- **Single-Select (**`**multiselect: false**`**)**
Der Wert wird **direkt als einzelner Text oder Zahl** übergeben (z. B. `"Offen"` oder `1`).
- **Multi-Select (**`**multiselect: true**`**)**
Der Wert ist ein **Array von Strings oder Zahlen**, z. B. `[Bluse, Kleidung, Oberteil]` oder `[1, 2]`.
Jeder enthaltene Wert wird in der Liste als **„aktiv“** markiert.


```javascript
currentValue: text(Status), // Bezeichnung deines Ninox-Feldes innerhalb von text()
currentValue: arcCustomBadge({
        uniqueId: "customBadge" + Nr,
        embedded: true,
        width: "100%",
        icon: "",
        iconPosition: "",
        fontSize: "",
        fontWeight: "700",
        borderRadius: "",
        singleColor: color(Status),
        fontColor: "",
        backgroundColor: "",
        borderColor: "",
        paddingY: "5px",
        paddingX: "10px",
        value: text(Status)
    }), // individuell gestaltetes customBadge mit der Bezeichnung deines Ninox-Feldes bei value
  currentValue: "", // default: es wird nicht der ausgewählte Wert angezeigt, sondern der placeholder
```

### items Block

**Pflichtfeld:** ✅

Der `items`-Block definiert die **Auswahlmöglichkeiten**, die im Dropdown angezeigt werden. Jede Option wird als Objekt mit bestimmten Eigenschaften angegeben – z. B. sichtbarer Text, interner Wert und aktiver Zustand.

**🔄 **Zwei Aufbauvarianten: Du kannst das `customSelect` auf zwei verschiedene Arten mit Werten befüllen:

1. **Dynamisch aus einer Ninox-Tabelle**

Ideal für Listen, die sich ändern können oder mit anderen Feldern verknüpft sind.


```javascript
items: let id := Nr;
        (select Status_Projekte).[{
            title: Titel,
            active: number(id.Status) = number(Nr),
            value: number(Nr)
            }]
```

2. **Manuelle Liste im Code**

Geeignet, um z. B. ein einfaches Auswahlfeld aus Ninox direkt nachzubauen, bzw. anzusteuern. (ohne externe Tabelle).


```javascript
items: [{
                title: "Offen",
                active: Status = 1,
                value: number(Nr)
            }, {
                title: "In Arbeit",
                active: Status = 2,
                value: number(Nr)
            }, {
                title: "Erledigt",
                active: Status = 3,
                value: number(Nr)
            }]
```

**🧩 Struktur pro Eintrag**

- `title` – Anzeige im Dropdown (Text oder Widget, z. B. `arcCustomIcon({ name: "check", iconSize: "16px" })` neben Label-Text)
- `value` – Der zu speichernde Wert
- `active` – Wann wird dieser Eintrag als ausgewählt markiert

💡 **`icon`** (am Select-Root) und **`currentValue`** unterstützen ebenfalls eingebettete Mini-Widgets – dieselbe Regel wie bei `items[].title`.

## 🎹 Tastaturverhalten im Vergleich

<figure><table><tbody><tr><th>Taste

</th><th>Single-Select Verhalten

</th><th>Multi-Select Verhalten

</th></tr><tr><td>**Tab**

</td><td>✅ Auswahl wird bestätigt➡️ Fokus springt weiter

</td><td>➡️ Fokus springt weiter🚫 Keine Bestätigung

</td></tr><tr><td>**Enter**

</td><td>✅ Auswahl wird bestätigt🔒 Select wird geschlossen

</td><td>✅ Auswahl wird bestätigt🔓 Select bleibt geöffnet

</td></tr><tr><td>**Escape**

</td><td>❌ Select wird geschlossen

</td><td>❌ Select wird geschlossen

</td></tr></tbody></table></figure>## ✅ Fazit

Das `customSelect`-Widget ist eine vielseitige Lösung für individuelle Auswahlfelder in Ninox – von einfachen Einzelauswahlen bis zu dynamischen Multi-Selects mit Hilfslogik.

Nutze es, wenn du mehr Kontrolle über Darstellung, Verhalten und Interaktion brauchst als Ninox von Haus aus bietet.

Mit klaren Parametern, flexiblen Datenquellen und voller Tastatursteuerung lässt sich das Widget nahtlos in jedes Formular oder Layout integrieren.

---

## Feature-Idee: Nice Select (moderner nativer Select)

💡 **Geplante Erweiterung:** Inspiration von [Nice Select](https://nerdy.dev/nice-select#try-it) – `appearance: base-select`, `::picker()`, Anchor Positioning, Spring-Animationen, sticky Gruppentitel, Squircle-Ecken. [CodePen](https://codepen.io/editor/argyleink/pen/019c1f28-bbc2-7bac-ad4a-a7e41d3730f1).
<!-- /host -->


---

# Short Numbers

Source: https://www.arc-rider.com/docs/mini-widgets/short-numbers


# Short Numbers

## AI Defaults (read first)

- **Function name**: `shortNumbers(value)` – helper function, not a widget.
- **Usage**: Formats large numbers: `1200` → `"1.2K"`, `3500000` → `"3.5M"`.
- **Use in KPI cards**: Always wrap large numeric values with `shortNumbers()`.

# Short Numbers

![](https://framerusercontent.com/images/zU4RZnOHOYqQGZD2v82pBREYQns.png)

Short Numbers ist eine Funktion, die es ermöglicht, lange Zahlen abzukürzen und so in einem komplexen Interface übersichtlicher darzustellen.

## Funktion

Die Funktion besteht aus einem Parameter, in den die darzustellende Zahl kommt.


```javascript
shortNumbers(") // Gibt so nichts aus, zeigt aber dass die Funktion einen Parameter verlangt.
shortNumbers(463299) // Zahlenwert fix reinschreiben
shortNumbers(Projekt.Umsatz) // Ninox-Feld referenzieren. Es muss ein Zahlenfeld sein, bzw. einen Zahlenwert ausgeben.
```


---

# Signature

Source: https://www.arc-rider.com/docs/mini-widgets/signature


<!-- host:react -->
# Signature in React

Eine Unterschrift auf einer Zeichenfläche erfassen und als Bild an deine Anwendung übergeben. Das Beispiel speichert lokal im Browser.

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

<!-- react-example: signature-01-empty.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetSignature } from '@arcrider/arcwidgets-react';

export default function Example() {
  const [value, setValue] = useState<string | undefined>();
  return (
    <ArcWidgetSignature
      data={{
        value,
        height: '220px',
        placeholder: 'Sign here',
        confirmLabel: 'Confirm',
        clearLabel: 'Clear',
      }}
      onSave={setValue}
      onClear={() => setValue(undefined)}
    />
  );
}
```

## Features ausprobieren

### Zeichnen, Nur-Lesen und Löschen

Unterschreibe mit Maus oder Touch und schalte auf Nur-Lesen. Dieses Beispiel speichert ausschließlich im React-State.

<!-- react-example: signature-01-empty.tsx -->
```tsx
import { useState } from 'react';
import { ArcWidgetSignature } from '@arcrider/arcwidgets-react';

export default function Example() {
  const [value, setValue] = useState<string | undefined>();
  return (
    <ArcWidgetSignature
      data={{
        value,
        height: '220px',
        placeholder: 'Sign here',
        confirmLabel: 'Confirm',
        clearLabel: 'Clear',
      }}
      onSave={setValue}
      onClear={() => setValue(undefined)}
    />
  );
}
```

## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

### data

Konfiguration vom Typ `ArcWidgetSignatureData`. Ü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).

### onSave

Die Unterschrift wurde bestätigt. Liefert eine PNG-Data-URL (`data:image/png;base64,…`) in Flächengröße mal Pixeldichte des Geräts. Gibst du ein Promise zurück, erscheint die Vorschau erst nach dessen Auflösung.

```typescript
onSave?: (dataUrl: string) => void | Promise<void>;
```

### onClear

Die Zeichenfläche wurde geleert.

```typescript
onClear?: () => void | Promise<void>;
```

## Konfiguration

Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.

### value

Gespeicherte Unterschrift als Bild-Data-URL, z. B. das Ergebnis von `onSave`. Sie erscheint als Vorschau mit Neu-unterschreiben-Button; Werte, die nicht mit `data:image/` beginnen, öffnen eine leere Zeichenfläche.

Typ: `string | null`.

### height

Höhe der Zeichenfläche, z. B. `"220px"`. Standard: `200px`.

Typ: `string`.

### autoSaveDelay

Millisekunden nach dem letzten Strich, bis die Unterschrift sich selbst speichert; `0` speichert sofort. Ohne diesen Wert speichert nur der Bestätigen-Button.

Typ: `number`.

### confirmLabel

Tooltip und barrierefreier Name des Bestätigen-Buttons. Standard: `Bestätigen`.

Typ: `string`.

### lineColor

Strichfarbe. Standard: `#000000`.

Typ: `string`.

### lineWidth

Strichstärke in CSS-Pixeln. Standard: `2`.

Typ: `number`.

### backgroundColor

Hintergrundfarbe der Fläche; sie ist Teil des gespeicherten Bilds. Standard: `#FFFFFF`.

Typ: `string`.

### placeholder

Hinweis auf der leeren Fläche.

Typ: `string`.

### readonly

Zeigt die gespeicherte Unterschrift ohne Bearbeitungselemente. Standard: `false`.

Typ: `boolean`.

### clearLabel

Tooltip und barrierefreier Name des Löschen-Buttons. Standard: `Löschen`.

Typ: `string`.

### editLabel

Tooltip und barrierefreier Name des Neu-unterschreiben-Buttons. Standard: `Neu unterschreiben`.

Typ: `string`.

## Verhalten und Grenzen

- `onSave` liefert eine PNG-Data-URL; `onClear` meldet das Leeren. Halte `data.value` mit dem gespeicherten Stand synchron.

- Speichern passiert über den Bestätigen-Button unten rechts. `autoSaveDelay` ist optional und bestätigt automatisch nach einer Pause. `readonly` verhindert Bearbeitung.

- Für dauerhafte oder geräteübergreifende Speicherung ersetze den lokalen Speicher durch deine API.

## Datentypen

Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: signature -->
```typescript
export interface ArcWidgetSignatureData {
	value?: string | null;
	height?: string;
	autoSaveDelay?: number;
	lineColor?: string;
	lineWidth?: number;
	backgroundColor?: string;
	placeholder?: string;
	readonly?: boolean;
	clearLabel?: string;
	confirmLabel?: string;
	editLabel?: string;
}

export interface ArcWidgetSignatureProps extends ArcReactWidgetProps<ArcWidgetSignatureData> {
	onSave?: (dataUrl: string) => void | Promise<void>;
	onClear?: () => void | Promise<void>;
}
```

## Einsatzbeispiele

- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
<!-- /host -->

<!-- host:ninox,vue -->
# Signature (Unterschrift)

## AI Defaults (read first)

- **uniqueId**: Pflicht, z. B. `"signature-" + Nr`.
- **recordId**: Raw `Nr` des Datensatzes (nicht `number(Nr)`).
- **fieldId**: `fieldId(Nr, "Feldname")` – **Textfeld** für die Data-URL (`data:image/png;base64,...`).
- **value**: Aktueller Feldinhalt aus der Formel übergeben, z. B. `Unterschrift`, damit Vorschau und Ansicht funktionieren.
- **height**: z. B. `"200px"` oder `"100%"` im umgebenden Layout.
- **confirmLabel**: Tooltip für den Bestätigen-Button unten rechts.
- **autoSaveDelay**: Optional. Nur setzen, wenn nach einer Pause automatisch gespeichert werden soll. Ohne Wert speichert nur Bestätigen. `0` = sofort nach einem Strich.
- **Persistence**: Speichern/Löschen über **Action Performer** (`type: "update"`). React: `onAction` — kein globales `database`.

# Unterschrift zeichnen

Das Widget `arcCustomSignature` zeichnet eine Unterschrift mit **Maus, Touch oder Stift** (Pointer Events) auf einem HTML-Canvas, exportiert sie als **PNG-Data-URL** und speichert sie per Action Performer (`update`) im angegebenen Textfeld. Mehrere getrennte Striche bleiben auf der Fläche, bis **Bestätigen** gedrückt wird.

## Anwendungscode

```javascript
arcCustomSignature({
    uniqueId: "signature-" + Nr,
    recordId: Nr,
    fieldId: fieldId(Nr, "Unterschrift"),
    value: Unterschrift,
    height: "220px",
    lineColor: "#000000",
    lineWidth: 2,
    backgroundColor: "#FFFFFF",
    placeholder: "Hier unterschreiben",
    readonly: false,
    clearLabel: "Löschen",
    confirmLabel: "Bestätigen",
    editLabel: "Neu unterschreiben"
})
```

## Parameter

| Parameter | Beschreibung |
|-----------|----------------|
| `uniqueId` | Eindeutige ID (HTML-`id`). |
| `recordId` | Datensatz, der aktualisiert wird. |
| `fieldId` | Ziel-Textfeld (Data-URL-String). |
| `value` | Optional: aktueller Wert für Anzeige/Vorschau. |
| `height` | Mindesthöhe des Widgets. |
| `lineColor` | Strichfarbe (Hex). |
| `lineWidth` | Strichbreite in CSS-Pixeln. |
| `backgroundColor` | Hintergrund der Zeichenfläche. |
| `placeholder` | Hinweistext bei leerer Fläche. |
| `readonly` | `true`: nur Anzeige, keine Eingabe. |
| `autoSaveDelay` | Optional: Auto-Bestätigen in ms nach `pointerup`. Ohne Wert nur über den Bestätigen-Button. |
| `clearLabel` | Tooltip und `aria-label` für das **Papierkorb-Icon** oben rechts (Zeichenmodus). |
| `confirmLabel` | Tooltip und `aria-label` für das **Häkchen** unten rechts (Zeichenmodus). |
| `editLabel` | Tooltip und `aria-label` für das **Refresh-Icon** oben links (Ansichtsmodus mit gespeicherter Signatur). |

## Verhalten

- **Ansicht**: Ist `value` eine gültige `data:image/…`-URL, wird die Unterschrift als Bild angezeigt; das **Refresh-Icon** oben links öffnet die Zeichenfläche erneut.
- **Speichern**: **Häkchen** unten rechts — erst dann wird die Unterschrift festgeschrieben. So bleiben getrennte Striche möglich. Optional `autoSaveDelay` für Auto-Bestätigen nach einer Pause.
- **Löschen**: **Papierkorb-Icon** oben rechts auf der Zeichenfläche – leert die Fläche und setzt das Feld auf `null`.

## NinoxScript-Hinweise

- Feld für die Signatur als **Text** anlegen (lange Data-URL).
- `fieldId` immer mit `fieldId(Nr, "…")` setzen.
- `value: Unterschrift` (Anzeigename) verwenden, damit das Widget den gespeicherten Inhalt kennt.
<!-- /host -->


---

# Sort

Source: https://www.arc-rider.com/docs/mini-widgets/sorting


# Sort

## AI Defaults (read first)

- **Function name**: `arcCustomSorting`.
- **uniqueId**: Required, e.g. `"sort-" + Nr`.
- **recordId**: Required, use raw `Nr`.
- **field**: Required, the field storing the current sort value.
- **items**: Array of sort options with `title` and `value`.

# Sort

![](https://framerusercontent.com/images/dOkxeX2Wt2QzZSAnYgYHLiUL5EY.png)

Um deine Daten easy per One-Klick zu sortieren, hilft dir das Sort-Mini-Widget. Dieses Mini Widget ist aktuell einsetzbar in der [Custom Table](/documentation/custom-table). Hier kannst du das Mini-Widget Sort als ***value*** einbinden.

## Gesamter Anwendungscode


```javascript
arcCustomSort({
            uniqueId: Nr,
            editable: true,
            recordId: current.Nr,
            fieldId: "H9", // Hier trägst du die Field Id von dem Feld ein, dass du triggerst.
            value: Position,
            valuePrefix: number(Nr) + ",",
            size: "",
            color: "",
            showIconsAlways: true,
            iconStart: "", // Fallback: "caret-up" | Hier fügst du das Custom Icon deiner Wahl ein.
            iconEnd: "",  // Fallback: "caret-down" | Hier fügst du das Custom Icon deiner Wahl ein.
        })
```

***editable*** definiert, ob du in das Input-Feld etwas eingeben kannst oder nicht.


```javascript
editable: true,
editable: false,
editable: "", // Fallback: true
```

***value*** ist der Wert, der als Grundlage für das ***iconStart*** und ***iconEnd*** getriggert wird.


```javascript
value: Position, // Hier sprichst du ein Ninox-Feld, wie beispielsweise ein Position-Zahlenfeld, an.
value: "", // Kein Fallback-Wert
```

***showIconAlways*** definiert die Sichtbarkeit deiner Icons, die bei der Sortierung angezeigt werden.


```javascript
showIconsAlways: true, // Icons werden immer angezeigt.
showIconsAlways: false, // Icons werden nur beim Hovern mit der Maus 🐭 angezeigt.
showIconsAlways: "", // Fallback: false
```

***valuePrefix*** ist für komplexe Eingaben mit Ninox-Hilfsfeldern gedacht. Ein Beispiel findest du in dem [Ninox-Webinar](https://youtu.be/knbcKbWVEUQ?si=I5GRrp3-QpeQrlVn&t=2395).


```javascript
valuePrefix: number(Nr) + ",",
```


---

# Text

Source: https://www.arc-rider.com/docs/mini-widgets/text


<!-- host:react -->
# Text in React

Text oder React-Inhalte mit einheitlicher Typografie und Ausrichtung 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



## Features ausprobieren

### Ellipsis, Ausrichtung und Typografie

Die feste Breite macht den Unterschied zwischen gekürztem und mehrzeiligem Text sichtbar.



## Komponenten-Props

### id

Optionale DOM-ID. Im Normalfall nicht nötig; ohne Angabe wird sie automatisch erzeugt.

### data

Konfiguration vom Typ `ArcWidgetTextData`. Ü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 Inhalt; `null` und `undefined` zeigen nichts an.

Typ: `ArcWidgetSlot`.

### width

Breite des Widgets. Standard: `100%`.

Typ: `string`.

### height

Höhe des Widgets, z. B. `"320px"`; `'auto'` behält die Inhaltshöhe. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe. Standard: `auto`.

Typ: `string`.

### alignX

Horizontale Position des Textblocks im Widget. Standard: `left`.

Typ: `'left' | 'center' | 'right'`.

### alignY

Vertikale Position des Textblocks im Widget. Standard: `top`.

Typ: `'top' | 'center' | 'bottom'`.

### fontSize

Schriftgröße als CSS-Wert. Standard: `13px`.

Typ: `string`.

### fontWeight

Schriftstärke. Standard: `400`.

Typ: `string | number`.

### fontColor

Schriftfarbe. Standard: `#000`.

Typ: `string`.

### lineHeight

Zeilenhöhe. Standard: `normal`.

Typ: `string`.

### textAlign

Ausrichtung umbrochener Zeilen innerhalb des Textblocks; den Block selbst positionierst du mit `alignX`. Standard: `left`.

Typ: `'left' | 'center' | 'right' | 'justify' | 'start' | 'end'`.

### textWrap

Umgang mit Leerraum und Umbruch (CSS `white-space`). Standard: `normal`.

Typ: `'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces'`.

### textScroll

`true` lässt den Text vertikal scrollen, wenn er `height` überschreitet; die Scrollleiste bleibt ausgeblendet. Standard: `false`.

Typ: `boolean`.

### textDirection

`'vertical'` dreht den Text, sodass er von unten nach oben gelesen wird. Standard: `horizontal`.

Typ: `'horizontal' | 'vertical'`.

### textDecoration

Linie unter, durch oder über dem Text: `type` (`underline`, `line-through`, `overline`) ist Pflicht; `style` (Standard `solid`), `color` (Standard `#000`) und `thickness` (Standard `1px`) sind optional.

Typ: `ArcWidgetTextDecoration`.

### truncate

Kürzt den Text auf eine Zeile mit Auslassungspunkten; braucht eine begrenzte Breite. Standard: `false`.

Typ: `boolean`.

## Verhalten und Grenzen

- `value` unterstützt JSX. Rich Text aus eigener Quelle ist möglich; für fremde Inhalte ist ein React-Textelement die sichere Wahl.

- `truncate` kürzt lange Texte. Eine begrenzte Breite ist dafür Voraussetzung.

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. Die Konfigurationsobjekte sind geschlossen: Ein falsch geschriebener oder nicht unterstützter Schlüssel wird als Typfehler gemeldet.

<!-- react-types: text -->
```typescript
export interface ArcWidgetTextDecoration {
	type?: 'underline' | 'line-through' | 'overline';
	style?: 'solid' | 'double' | 'dotted' | 'dashed' | 'wavy';
	color?: string;
	thickness?: string;
}

export interface ArcWidgetTextData {
	value?: ArcWidgetSlot;
	width?: string;
	height?: string;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom';
	fontSize?: string;
	fontWeight?: string | number;
	fontColor?: string;
	lineHeight?: string;
	textAlign?: 'left' | 'center' | 'right' | 'justify' | 'start' | 'end';
	textWrap?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces';
	textScroll?: boolean;
	textDirection?: 'horizontal' | 'vertical';
	textDecoration?: ArcWidgetTextDecoration;
	truncate?: boolean;
}

export interface ArcWidgetTextProps extends ArcReactWidgetProps<ArcWidgetTextData> {}
```

## 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)
<!-- /host -->

<!-- host:ninox,vue -->
# Text

## AI Defaults (read first)

- **Function name**: `arcCustomText`.
- **value**: The text content. Supports NinoxScript expressions.
- **Use for type consistency**: When `if/else` mixes text and widget, wrap the text branch in `arcCustomText({value: ...})`.
- **fontSize**, **fontColor**, **fontWeight**: Direct properties (not nested).
- **truncate**: `true` enables ellipsis when the text exceeds the container width (set an explicit `width`).
- **No uniqueId needed** for simple text display.

# Text

![](https://framerusercontent.com/images/QPDhVJgrgK68jBZ7OahdkAomXYQ.png)


## Anwendungscode


```javascript
arcCustomText({
        uniqueId: " + Nr,
        embedded: true,
        width: "",
        height: "",
        alignY: "",
        alignX: "",
        fontSize: "",
        fontWeight: "",
        fontColor: "",
        lineHeight: "",
        textWrap: "",
        textScroll: "",
        textAlign: "",
        textDirection: "horizontal",
        textDecoration: {
            type: "",
            style: "",
            color: "",
            thickness: ""
        },
        truncate: "",
        value: ""
    })
```

### uniqueId

Die*** **uniqueId* vergibst du individuell, sie muss einzigartig sein. Sinn dahinter ist: Wenn du mehrere customText mit unterschiedlichen Settings auf deiner Oberfläche anzeigst, überschreiben sich die Styles nicht.


```javascript
uniqueId: Nr, // Ninox-Feld
uniqueId: "Aufgabe Beschreibung", // Text in "
```

### embedded

Den Parameter ***embedded*** nutzt du, wenn du der Text ***nicht ***innerhalb eines anderen Widgets liegt. 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 Text eingebettet in anderes Widget
embedded: "", // default: true
```

### width

Bei ***with*** definierst du, wie breit der Container deines customText sein soll.


```javascript
width: "100%", // Prozent-Werte oder "80px" Pixel-Werte
width: "auto", // witdh passt sich an Inhalt an
width: "", // default: 100%
```

### height

Bei ***height*** definierst du, wie hoch der Container deines customText sein soll.


```javascript
height: "100%", // Prozent Werte
height: "100px", // Pixel Werte
height: "", // default: auto
```

### alignY

Den Parameter ***alignY*** nutzt du, um zu bestimmen, ob der Container des customText auf der Y-Achse oben, unten oder mittig angeordnet sein soll.


```javascript
alignY: "bottom", // top, bottom, center
alignY: "", // default: top
```

### alignX

Den Parameter ***alignX*** nutzt du, um zu bestimmen, ob der Container des customText auf der X-Achse links, rechts oder mittig angeordnet sein soll.


```javascript
alignX: "right", // left, right, center
alignX: "", // default: left
```

### fontSize

Mit ***fontSize*** bestimmst du die Schriftgröße deines Textes.


```javascript
fontSize: "12px", // Pixel Werte
fontSize: "", // default: 12px
```

### fontWeight

Bei*** fontWeight*** kannst du die Dicke deiner Schrift definieren.


```javascript
fontWeight: "normal", // CSS-Values (bold, lighter etc.)
fontWeight: "800", // Zahl 100-800 in 100er Schritten (400=normal, 800=bold)
fontWeight: "", // default: normal/400
```

### fontColor

Mit*** fontColor*** definierst du die Schriftfarbe deines customText.


```javascript
fontColor: "#000000", // HEX Werte
fontColor: "rgb(77,166,255)", // RGB Werte
fontColor: "", // default: #000
```

### lineHeight

Mit*** lineHeight ***bestimmst du den Abstand zwischen den Textzeilen.


```javascript
lineHeight: "5px", // fixe line-height in px, pt, cm etc.
lineHeight: "1.5", // punkt-getrennte Zahl, multipliziert mit font-size
lineHeight: "150%", // line-height in Prozent von font-size
lineHeight: "", // default: normal
```

### textWrap

Mit textWrap bestimmst du, wie dein Text umgebrochen werden soll. Du kannst gängige CSS Values für white-space nutzen.


```javascript
textWrap: "normal", // automatischer Zeilenumbruch, wenn verfügbaren Platz überschritten
textWrap: "nowrap", // Text bleibt in einer Zeile, auch wenn verfügbarer Platz überschritten
textWrap: "pre", // Text wird genau so angezeigt wie im HTML-Code, mit Leerzeichen und Zeilenumbrüchen
textWrap: "pre-wrap", // Text wird umgebrochen, wenn verfügbarer Platz überschritten, behält Leerzeichen und Zeilenumbrüche bei
textWrap: "pre-line", // Text wird wie "pre-wrap" behandelt, aber behält normale Zeilenumbrüche bei und entfernt zusätzliche Leerzeichen
textWrap: "", // default: normal
```

### textScroll

Mit ***textScroll*** kannst du mit true oder false einstellen, ob der Text, wenn er mehr Platz braucht, als der Container hergibt (bestimmst du mit width und height), scrollbar sein soll oder abgeschnitten sein soll.


```javascript
textScroll: true, // Der Text wird scrollbar, wenn er den Container überschreitet.
textScroll: false, // Der Text wird abgeschnitten, wenn er den Container überschreitet.
textScroll: "", // default: true
```

### textAlign

Bei ***textAlign***  bestimmst du wie der Text angeordnet sein soll, links- oder rechtsbündig, zentriert oder über die Zeile verteilt.


```javascript
textAlign: "right", // left, right, center
textAlign: "justify", // streckt den Text so, dass jede Linie dieselbe Breite hat (wie zB in Zeitungen)
textAlign: "", // left
```

### textDirection

Mit dem Parameter ***textDirection ***kannst du bestimmen, ob der Text horizontal oder vertical ausgerichtet sein soll.


```javascript
textDirection: "vertical", // vertical, horizontal
textDirection: "", // horizontal
```

### textDecoration

Bei ***textDecorationSettings*** kannst du mit dem Parameter type deinen Text Unter- und Durchstreichen bzw. eine Linie über, und auch sowohl unter als auch über, dem Text erzeugen. Außerdem kannst du diese Linie mit style, color und thickness individuell stylen.


```javascript
textDecoration: {
            type: "",
            style: "",
            color: "",
            thickness: ""
        }
```

Der Parameter ***type*** bestimmt die Art der Linie bzw. die Position.


```javascript
type: "none", // keine Linie
type: "overline", // Linie oberhalb des Textes
type: "line-throug", // Text wird durchgestrichen
type: "underline", // Text wird unterstrichen
type: "overline underline", // Erzeugt eine Linie ober- und unterhalb des Textes
type: "", // default: keine Linie
```

Der Parameter ***style*** bestimmt den style der Linie.


```javascript
style: "solid", // gerade Linie
style: "double", // doppelte Linie
style: "dotted", // gepunktete Linie
style: "dashed", // gestrichelte Linie
style: "wavy", // gewellte Linie
style: "", // default: solid
```

Der Parameter ***color*** bestimmt die Farbe der Linie.


```javascript
color: "#fff", // hex-code Farben
color: "rgb(249, 201, 36)", // rgb() Farben
color: "", // default: #000
```

Der Parameter ***thickness*** bestimmt die Dicke der Linie.


```javascript
thickness: "7px", //
thickness: "", // default: 1px
```

### truncate

Mit ***truncate*** kannst du langen Text mit Ellipsis (`…`) abschneiden, wenn er breiter ist als der Container (typisch mit fester `width`).

```javascript
truncate: true, // Text wird einzeilig abgeschnitten mit Ellipsis
truncate: false, // kein Truncate (default)
truncate: ", // default: false
```

### value

Bei ***value*** setzt du den Wert ein, der als customText ausgegeben werden soll. Das kann entweder geschriebener Text in " sein oder ein Ninox Feld. Fall es kein Ninox-Textfeld ist, denk dran den Wert in *text()* einzubinden.


```javascript
value: "Dies ist mein customText.", // manuell eingefügter Text
value: Beschreibung, // Ninox Wert
value: "", // gibst du keinen value ein, wird nichts ausgegeben
```

#### Tipp für schmale Spalten:

Bei der customTable kannst du nun mithilfe des customText die Spalten-Titel vertical darstellen, so sparst du Platz  bei Zellen, die zB nur eine Checkbox beinhalten und stellst Elementen, die mehr Raum benötigen, dementsprechend mehr zur Verfügung💡

![](https://framerusercontent.com/images/IzGhHmFNjffftaps5KTEwHMzwSc.png)

---

## Feature-Idee: Stifthervorhebung (Handwritten Highlight)

💡 **Geplante Erweiterung:** Text mit einem realistischen „Textmarker“-Effekt versehen (wie handgeschrieben markiert). Referenz: [CodePen](https://codepen.io/vii120/pen/KwMBaaY) – Varianten: gelb, grün, pink mit `conic-gradient` + `linear-gradient`.
<!-- /host -->


---

# Farben und Themes in React

Source: https://www.arc-rider.com/docs/themes/react-theme


# Farben und Themes in React

Leite die Widget-Farben aus dem Theme deiner React-Anwendung ab. Die verfügbaren Style-Felder unterscheiden sich pro Widget: Table verwendet unter anderem `styles`, `header` und Zellfarben; Button verwendet direkte Farben in `data`.

## Ein gemeinsamer Farbsatz



## Zusammengesetzte Oberflächen

Gib denselben Farbsatz auch an JSX-Inhalte wie Badges, Buttons und Fortschrittsanzeigen weiter. Ein äußerer Dark-Mode-Schalter überschreibt nicht automatisch alle expliziten Widget-Farben. Prüfe Kontrast sowie Hover-, Auswahl- und Leerzustände.


---

# Theme: Clean White

Source: https://www.arc-rider.com/docs/themes/custom-table-clean-white


# Theme: Clean White

# Theme "Clean White"

Das Theme Clean White kannst du in dem Widget [Custom Table ](/custom-table)anwenden. Hier gibst du unter dem Parameter "theme" folgenden Anwendungscode ein: 

## Anwendungscode 


```javascript
arcCustomThemeCleanWhite({
	uniqueId: "Projektliste Demo 1"
				})
```

## Beispiel

Hier siehst du du ein Beispiel-Bild für das Theme Clean White. Die Spalten werden ohne Trennstriche dargestellt. Auch die linke und rechte Border sind ausgelassen. Lediglich die Zeilen werden durch eine feine Border getrennt.

![](https://framerusercontent.com/images/uUWowsTh220sClRN9Ar8zVa5xYE.png)


---

# Theme: Naked

Source: https://www.arc-rider.com/docs/themes/theme-naked


# Theme: Naked

# Theme "Naked"

![](https://framerusercontent.com/images/Satd30fzY0art6F5jdYlPS0MCo.png)

## Gestalte deine Tabelle individuell: Das Theme "Naked" im Widget Custom Table

Das Theme Naked bietet dir die Möglichkeit, deine Tabelle in einem völlig neuen Design zu präsentieren. Mit diesem Theme kannst du auf klassische Elemente wie Rahmenlinien, Header oder Footer verzichten und so ein minimalistisches Erscheinungsbild schaffen. Perfekt für alle, die ihre Daten auf das Wesentliche reduziert und stilvoll präsentieren möchten.

## Was macht das Theme "Naked" besonders?

Die Funktionalität bleibt trotz des minimalistischen Designs vollständig erhalten – Hover-Aktionen oder Click-Actions beispielsweise funktionieren wie gewohnt. Zusätzlich kannst du Zwischenabstände (gap) individuell anpassen, sowohl zwischen den einzelnen Zeilen (rows) als auch den Spalten (columns). Das verleiht deiner Tabelle nicht nur Struktur, sondern sorgt auch für ein aufgeräumtes und modernes Layout.

## So wendest du das Theme an

Um das Theme "Naked" in deiner [Custom Table](/custom-table) zu nutzen, fügst du folgenden Anwendungscode hinter dem Paramter `theme` ein: 

<blockquote>*Wichtig: Die uniqueId des Themes muss dieselbe sein, wie die uniqueListId der Table, in der das Theme eingesetzt wird !*

</blockquote>## Anwendungscode 


```javascript
arcCustomThemeNaked({
				uniqueId: "Aufgaben Demo 1" + Nr,
				rowSettings: {
					gap: "10px",
                    borderRadius: ""
				},
				columnSettings: {
					gap: "40px"
				}
			}),
```

## Beispiel

Im folgenden Beispiel siehst du den Anwendungscode des oben dargestellten Bildes. Dieser umfasst eine Custom Table, die Termine von Mitarbeitern darstellt. Hier sind sowohl Header als auch Footer ausgeblendet. Durch das Theme sind keinerlei Rahmenlinien in der Tabelle zu sehen und die einzelnen Zeilen sind durch ein gap von 10px getrennt. 


```javascript
let current := this;
let list := (select Termine from 0 to 30);
let data := {
		uniqueListId: "Aufgaben Demo 1" + Nr,
		tableId: tableId(first(list)),
		height: "620px",
		width: "100px",
		groupedBy: "",
		header: {
			showHeader: false
		},
		theme: arcCustomThemeNaked({
				uniqueId: "Aufgaben Demo 1" + Nr,
				rowSettings: {
					gap: "10px"
				},
				columnSettings: {
					gap: "10px"
				},
                borderRadius: ""
			}),
		embedded: false,
		table: list.[{
				recordId: Nr,
				rowColor: "#ededed",
				rowHeight: "auto",
				rowPaddingY: "10px",
				groupRowColor: "",
				columns: [{
						field: "Kategorie Icon",
						title: "",
						width: "35px",
						color: "",
						backgroundColor: "",
						align: "left",
						paddingX: "",
						paddingY: "",
						value: arcCustomIcon({
								iconSet: "phosphor",
								name: "circle-fill",
								iconSize: "25px",
								color: record('Kategorie Aufgabe',number(Kategorie)).Farbe
							}),
						actions: [{
								type: "popup",
								showPopupButton: false,
								recordId: Nr
							}]
					}, {
						field: "Feldname für Feld-ID",
						title: "",
						color: "",
						backgroundColor: "",
						width: "",
						align: "left",
						paddingX: "",
						paddingY: "",
						value: arcCustomLayout({
								comment: "---------------------------------- LAYOUT TITEL UND KATEGORIE ----------------------------------",
								uniqueId: "Titel und Kategorie " + Nr,
								embedded: true,
								direction: "vertical",
								alignX: "left",
								alignY: "center",
								width: "100%",
								height: "",
								gap: "2px",
								scrollSettings: {
									scrollY: false,
									scrollX: false
								},
								blocks: [{
										width: "",
										height: "auto",
										lineHeight: "",
										alignX: "left",
										color: "",
										styles: "",
										value: arcCustomText({
												uniqueId: "Bezeichnung " + Nr,
												fontSize: "13px",
												fontWeight: "600",
												fontColor: "",
												value: Auftrag.last(Aufgaben.Aufgabe)
											})
									}, {
										width: "",
										height: "auto",
										lineHeight: "",
										alignX: "left",
										color: "",
										value: arcCustomText({
												uniqueId: "Bezeichnung " + Nr,
												fontSize: "13px",
												fontWeight: "",
												fontColor: "#9aa3af",
												value: text(Kategorie)
											})
									}]
							}),
						actions: [{
								type: "popup",
								showPopupButton: false,
								recordId: Nr
							}]
					}, {
						field: "",
						title: "",
						width: "",
						color: "",
						backgroundColor: "",
						align: "left",
						paddingX: "",
						paddingY: "",
						value: arcCustomLayout({
								comment: "---------------------------------- LAYOUT UHRZEIT & DATUM ----------------------------------",
								uniqueId: "Datum und Uhrzeit " + Nr,
								embedded: true,
								fullscreen: false,
								ninoxVersion: "",
								page: true,
								fullscreenMode: "",
								showAdminTools: true,
								hideHeaderIcons: true,
								direction: "horizontal",
								alignX: "left",
								alignY: "center",
								width: "",
								height: "",
								gap: "10px",
								backgroundColor: "",
								paddingY: "",
								paddingX: "",
								styles: "",
								scrollSettings: {
									scrollY: false,
									scrollX: false
								},
								blocks: [{
										width: "auto",
										height: "auto",
										lineHeight: "",
										alignX: "left",
										color: "",
										styles: "",
										value: arcCustomIcon({
												iconSet: "phosphor",
												name: "clock",
												iconSize: "25px",
												color: "#9aa3af"
											})
									}, {
										width: "fraction",
										height: "auto",
										lineHeight: "",
										alignX: "left",
										color: "",
										value: arcCustomText({
												uniqueId: "Bezeichnung " + Nr,
												fontSize: "13px",
												fontWeight: "600",
												fontColor: "#9aa3af",
												value: 'Datum von' + ", " + Von + " - " + Bis
											})
									}]
							}),
						actions: [{
								type: "popup",
								showPopupButton: false,
								recordId: Nr
							}]
					}, {
						field: "Mitarbeiter",
						title: "",
						width: "",
						color: "",
						backgroundColor: "",
						align: "left",
						paddingX: "",
						paddingY: "",
						value: Mitarbeiter.'Bild-und_Name',
						actions: [{
								type: "popup",
								showPopupButton: false,
								recordId: Nr
							}]
					}]
			}],
		footer: {
			showFooter: false
		}
	};
arcCustomTable(data)
```


---

# Ninox: Wie baue ich Builds ein und wie laufen Updates?

Source: https://www.arc-rider.com/docs/faq/wie-man-builds-einbaut-und-updatet


# Ninox: Wie baue ich Builds ein und wie laufen Updates?

## Was ist ein Build?

Ein **Build** ist das fertige Code-Paket für dein Ninox-Team. Nicht jedes Widget einzeln — Universe macht aus den Widgets deines Projekts **einen** Textblock.

So hängt das zusammen:

1. **Projekt** — dein Arbeitsbereich in Universe. Dort liegen Lizenz und Widgets.
2. **Build** — der daraus erzeugte Code. Den kopierst du einmal in die **globalen Funktionen** von Ninox.
3. **Anwendungscode** — die kurze Formel im Formelfeld, mit der du ein einzelnes Widget auf einer Seite anzeigst.

Ohne den Build im Global Code kann Ninox die Widgets nicht laden. Den Anwendungscode brauchst du trotzdem pro Stelle, an der ein Widget erscheinen soll.

Universe hält den **Standard-Build** automatisch aktuell: Neue Widgets und neue Widget-Versionen kommen von selbst hinein, auch größere Versionssprünge. Widgets, die du bewusst auf eine Version festgelegt hast, bleiben dabei unverändert. Eigene benannte Builds nutzt du im Expertenmodus, wenn du einen Stand festhalten willst — zum Beispiel vor einem Go-Live.

---

## Schritt 1: Code in Universe kopieren

1. Gehe in dein Universe-Projekt.
2. Hinterlege unter **„URL freischalten“** zuerst deine Ninox-URL oder Team-ID. Erst dann steckt die Lizenz im Code.
3. Klicke unter **„In Ninox einfügen“** bei **„Globalen Code kopieren“** auf **Kopieren**. Du musst den Code dafür nicht ansehen.

Eigene Builds, Widget-Versionen und die Code-Vorschau findest du über den Schalter **Expertenmodus** oben neben „Ninox“.

## Schritt 2: In Ninox einsetzen (Erst-Setup)

1. Wechsel in deine Ninox-Datenbank im **Admin-Modus**.
2. Klicke auf die **drei Punkte** neben dem Datenbanknamen oben links.
3. Gehe auf **„Optionen“ > „Globale Funktionen“**.
4. Füge den kopierten Code am Ende des Textfeldes ein und speichere.

Zusätzlich einmalig als **Trigger nach Öffnen** (Datenbankoptionen, ganz oben):

```ninox
dialog("ArcRider initialization", html(arcRiderWidgetManager()), ["close"])
```

Damit startet die Widget-Engine, sobald die Datenbank geöffnet wird. In deinem Universe-Projekt kopierst du dieses Script mit **„Start-Code kopieren“**.

---

## Wie funktionieren Updates?

Nach dem ersten Einfügen hakst du in deinem Universe-Projekt **„Ja, Code ist eingefügt“** ab. Ab dann weiß Universe, welcher Stand in deinem Ninox läuft.

Wenn wir Fehler beheben, neue Widget-Versionen erscheinen oder sich deine URLs ändern, erzeugt Universe einen neuen Code. In deinem Projekt erscheint dann das Banner **„Neues Update verfügbar“** mit einer Liste, welche Widgets sich geändert haben. Größere Versionssprünge sind dort als **Hauptversion** markiert; prüfe danach kurz deine Widgets.

So aktualisierst du Ninox sicher:

1. Klicke im Banner auf **„Neuen Code kopieren“**.
2. Öffne die **globalen Funktionen** in Ninox.
3. Suche den alten Arc-Rider-Block. Er beginnt mit einem klaren Header (ASCII-Wortmarke und `Build ID`).
4. Ersetze diesen Block vollständig durch den neuen Code.

Achte darauf, dass deine eigenen globalen Funktionen oberhalb oder unterhalb des Arc-Rider-Blocks unberührt bleiben.

Zurück in Universe klickst du auf **„Ja, ich habe die neueste Version eingefügt“**. Dann verschwindet das Banner bis zum nächsten Update. Den Start-Code musst du bei Updates nicht neu einfügen.


---

# React: Fehlerbehebung

Source: https://www.arc-rider.com/docs/faq/react-troubleshooting


# React: Fehlerbehebung

## Das Widget bleibt leer

Prüfe zuerst, ob du den exportierten Komponentennamen verwendest und ob alle Optionen in `data` liegen. Die [Komponentenübersicht](/docs/react/intro/react-components) zeigt die verfügbaren Exporte.

Eine Höhe von `100%` funktioniert nur in einem Elterncontainer mit berechenbarer Höhe. Beginne zum Eingrenzen mit `height: "320px"`. Bei Table braucht jede Spalte eine Breite, mindestens eine `fraction`.

## Ein Klick löst keinen Callback aus

Aktiviere die Klickbarkeit an der richtigen Stelle: etwa an der Table-Zeile, einer Kanban-Karte oder einem Step. Prüfe die Callback-Signatur in der Widget-Referenz. Eine ID ist keine Callback-Position; manche Events liefern Indizes, andere Werte.

## Nach dem Speichern springt die Anzeige zurück

Übernimm das bestätigte Ergebnis in React-State und leite ein neues `data`-Objekt daraus ab. Das Widget speichert nicht selbst in deiner Datenbank. Beim Kanban muss `onItemDrop` das Speicher-Promise zurückgeben.

## TypeScript erkennt einen Callback oder JSX-Slot nicht

Diese Referenzen gehören zu `0.1.0-alpha.5`. Vergleiche deine installierte Version und vermeide gemischte Kopien des Pakets. Die Typen befinden sich im Paket; du benötigst kein zusätzliches Widget-Typenpaket.

## Server Rendering

Die Widget-Laufzeit verwendet Browser-APIs. Importiere sie in einer Anwendung mit Server Rendering erst im Browser. Eine reine Client-Markierung reicht nicht in jedem Framework, wenn Module schon auf dem Server ausgewertet werden. Dieses vollständige Beispiel verschiebt den Laufzeit-Import in einen Effekt; der Typimport wird beim Build entfernt:

```tsx
import { useEffect, useState } from 'react';
import type { ComponentType } from 'react';
import type { ArcWidgetButtonProps } from '@arcrider/arcwidgets-react';
export default function Example() {
  const [Button, setButton] =
    useState<ComponentType<ArcWidgetButtonProps> | null>(null);
  const [error, setError] = useState(false);
  useEffect(() => {
    let active = true;
    import('@arcrider/arcwidgets-react')
      .then((module) => {
        if (active) setButton(() => module.ArcWidgetButton);
      })
      .catch(() => {
        if (active) setError(true);
      });
    return () => {
      active = false;
    };
  }, []);
  if (error) return <p role="alert">Could not load widget.</p>;
  return Button ? (
    <Button
      data={{
        title: 'Ready',
      }}
    />
  ) : (
    <p>Loading widget …</p>
  );
}
```

Nutze alternativ den Mechanismus deines Frameworks, der Server Rendering für diese Komponente ausdrücklich deaktiviert. Ein stabiler Platzhalter vermeidet Layoutsprünge.

## React Strict Mode

Entwicklung kann Komponenten mehrfach auf- und abbauen. Löse Speichervorgänge in Interaktions-Callbacks aus, nicht beim Rendern. Vergib stabile eigene IDs nur dort, wo du sie benötigst; dieselbe ID darf nicht gleichzeitig mehrfach im Dokument vorkommen.

## Ein Lizenzhinweis bleibt sichtbar

Ein Eintrag der Domain im Portal allein konfiguriert das npm-Paket derzeit nicht. Siehe [Paket und Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung).


---

# React: Wie funktionieren Paket und Lizenzierung?

Source: https://www.arc-rider.com/docs/faq/react-paket-und-lizenzierung


# React: Paket und Lizenzierung

`@arcrider/arcwidgets-react` enthält die Komponenten, Styles, Typen und vollständige Beispiele. Die Laufzeit wird in deine Anwendung eingebunden. Diese Dokumentation beschreibt `0.1.0-alpha.6`.

## Lokale Entwicklung

Installiere das Paket wie unter [React einrichten](/docs/react/intro/setup-react) beschrieben. Auf `localhost` und `127.0.0.1` erscheint kein Lizenzhinweis. Mini-Widgets benötigen auch für den produktiven Einsatz keine Premium-Freischaltung im Rahmen der Nutzungsbedingungen.

## MCP-Apps / Agent-Chat

In MCP-Apps bzw. vergleichbaren Agent-Chat-Umgebungen (sandboxed iframe, zum Beispiel Claude oder ChatGPT) erscheint kein Lizenzhinweis.

## Premium-Widgets auf einer Live-Domain

Eine Projektlizenz und die technische Aktivierung der Laufzeit sind zwei Schritte. Hinterlege die Produktions-Domain im Universe-Projekt und kläre die Aktivierung des npm-Pakets mit [support@arc-rider.com](mailto:support@arc-rider.com).

Der aktuelle Alpha-Stand stellt noch keinen öffentlichen Initialisierungsaufruf für die Lizenz bereit und lädt die Projektfreischaltung nicht automatisch aus dem Portal. Eine gespeicherte Domain allein entfernt den Hinweis deshalb nicht zuverlässig aus einer separat installierten React-App. Verwende die für dein Projekt bereitgestellte Aktivierung; erfinde keinen API-Key-Prop oder Initialisierungsaufruf.

## Lizenzhinweis

Auf einer nicht aktivierten Live-Domain kann bei Premium-Widgets ein Hinweis in der Oberfläche und Konsole erscheinen. Die Bedienelemente bleiben funktionsfähig; der Hinweis ersetzt keine Lizenz. Prüfe die technische Aktivierung auf der tatsächlichen Ziel-Domain vor der Freigabe.

Die Kennzeichnung einer Umgebung als Entwicklung oder Staging im Portal wird nicht automatisch in die React-App übertragen. Für öffentlich erreichbare Test-Domains muss die technische Aktivierung ebenfalls geprüft werden.

[Komponentenübersicht](/docs/react/intro/react-components) · [Preise und Projektmodell](/docs/react/faq/wie-sich-preise-zusammensetzen).


---

# Was bedeutet der Lizenzhinweis (Watermark) in der Produktion?

Source: https://www.arc-rider.com/docs/faq/lizenzhinweis-watermark-produktion


<!-- host:react -->
# Lizenzhinweis in React

Premium-Widgets können auf einer nicht aktivierten Live-Domain einen Hinweis in Oberfläche und Konsole anzeigen. Mini-Widgets und lokale Entwicklung auf `localhost` oder `127.0.0.1` zeigen ihn nicht.

## Bedienbarkeit

Der Hinweis sperrt keine Widget-Funktionen. Deine Anwendung bleibt für Datenzugriff und Speicherung zuständig.

## Aktivierung prüfen

Das npm-Paket übernimmt Portal-Einträge derzeit nicht automatisch. Eine gespeicherte Produktions-Domain allein ist deshalb keine technische Aktivierung deiner React-App. Prüfe die konkrete Domain und die für dein Projekt bereitgestellte Freischaltung.

[React-Paket und Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung) beschreibt den aktuellen Alpha-Stand und den Kontakt zur Aktivierung.
<!-- /host -->

<!-- host:ninox -->
# Was bedeutet der Lizenzhinweis (Watermark) in der Produktion?

Wenn du Widgets in ein Projekt legst, sind die Funktionen sofort da. Du kannst Premium-Widgets (Table, Kanban, Calendar, …) vollständig testen, bevor du Ultimate kaufst.

Ohne Ultimate erscheint in einer **Produktionsumgebung** ein Hinweis — unten in der Oberfläche und einmal in der Browser-Konsole. Die Widgets bleiben bedienbar.


![Lizenzhinweis als Toast in der Oberfläche und als Meldung in der Konsole](/docs-assets/lizenzhinweis.png)


## Wann erscheint der Hinweis?

- Du nutzt **Premium-Widgets** und das Projekt hat kein **Ultimate-Paket**.
- Die App läuft auf einer **Produktions-Umgebung**, die nicht im Universe-Projekt hinterlegt ist.


Bei Ninox zählt die Private-Cloud-URL, die On-Premise-URL oder die Public-Cloud-**Team-ID**.


Mini-Widgets zeigen den Hinweis nicht. Auf `localhost` und in Test-Stages erscheint er ebenfalls nicht.

## Was wird blockiert?

**Nichts.** Der Hinweis ist eine Lizenzanzeige:

- Widgets frieren nicht ein.
- Daten werden weiter geladen und gespeichert.
- Bedienung und Performance bleiben erhalten.

In der Konsole steht dieselbe Information hinter dem gelben Badge **Arc Widgets**. Das hilft, wenn jemand die Seite prüft und den Toast schon weggeklickt hat.

## Wie entferne ich den Hinweis?

Sobald Ultimate für das Projekt aktiv ist, verschwindet er:


Im Universe-Projekt den Build neu holen und den Global Code in Ninox ersetzen. Der neue Build enthält die Freischaltung. Details: [Ninox Builds](/docs/faq/wie-man-builds-einbaut-und-updatet).


Preise: [Wie berechnen sich die Preise?](/docs/faq/wie-sich-preise-zusammensetzen).
<!-- /host -->

<!-- host:vue -->
# Was bedeutet der Lizenzhinweis (Watermark) in der Produktion?

Wenn du Widgets in ein Projekt legst, sind die Funktionen sofort da. Du kannst Premium-Widgets (Table, Kanban, Calendar, …) vollständig testen, bevor du Ultimate kaufst.

Ohne Ultimate erscheint in einer **Produktionsumgebung** ein Hinweis — unten in der Oberfläche und einmal in der Browser-Konsole. Die Widgets bleiben bedienbar.


Der Hinweis ist ein Toast unten in der App und dieselbe Meldung einmal in der Browser-Konsole hinter dem gelben Badge **Arc Widgets**.


## Wann erscheint der Hinweis?

- Du nutzt **Premium-Widgets** und das Projekt hat kein **Ultimate-Paket**.
- Die App läuft auf einer **Produktions-Umgebung**, die nicht im Universe-Projekt hinterlegt ist.


Bei Vue zählt die hinterlegte Live-Domain (inkl. Subdomains).


Mini-Widgets zeigen den Hinweis nicht. Auf `localhost` und in Test-Stages erscheint er ebenfalls nicht.

## Was wird blockiert?

**Nichts.** Der Hinweis ist eine Lizenzanzeige:

- Widgets frieren nicht ein.
- Daten werden weiter geladen und gespeichert.
- Bedienung und Performance bleiben erhalten.

In der Konsole steht dieselbe Information hinter dem gelben Badge **Arc Widgets**. Das hilft, wenn jemand die Seite prüft und den Toast schon weggeklickt hat.

## Wie entferne ich den Hinweis?

Sobald Ultimate für das Projekt aktiv ist, verschwindet er:


Produktions-Domain im Universe-Projekt hinterlegen.


Preise: [Wie berechnen sich die Preise?](/docs/faq/wie-sich-preise-zusammensetzen).
<!-- /host -->


---

# Was ist ein Widget-Partner und welche Vorteile habe ich davon?

Source: https://www.arc-rider.com/docs/faq/was-ist-ein-widget-partner-und-welche-vorteile-habe-ich-davon


# Was ist ein Widget-Partner und welche Vorteile habe ich davon?

Partner sind Agenturen und Integratoren, die Arc Rider Widgets **in Kundenlösungen** einsetzen. Arc Rider stuft Organisationen als Partner ein.

Für den Einsatz beim Endkunden gilt:

- **Ein Universe-Projekt je Endkunde.** Jeder Lizenzkontext hat ein eigenes Package. Den Preis gegenüber deinem Kunden setzt du selbst.
- Du trittst **im eigenen Namen** auf. Vertragspartner deiner Mandanten bist du, nicht Arc Rider.
<!-- host:ninox -->
- Builds, Umgebungen und Rechnungen bleiben pro Kundenprojekt getrennt.
<!-- /host -->
<!-- host:react -->
- Lizenz, Produktions-Domains und Rechnungen bleiben pro Kundenprojekt getrennt.
<!-- /host -->
<!-- host:vue -->
- Lizenz, Produktions-Domains und Rechnungen bleiben pro Kundenprojekt getrennt.
<!-- /host -->

Konditionen (Rabattcode, Angebot, Freischaltung) vereinbaren wir individuell.

Zusätzlich gibt es das **Ambassador-Programm**: öffentlich geteilte Arc-Rider-Erfahrung bringt Credits, die du gegen Gutscheine für neue Projekte einlösen kannst. Überblick auf der [Preisseite](/pricing).

Partner-Einstufung: [support@arc-rider.com](mailto:support@arc-rider.com).


---

# Wie berechnen sich die Preise für Widgets?

Source: https://www.arc-rider.com/docs/faq/wie-sich-preise-zusammensetzen


# Wie berechnen sich die Preise für Widgets?

Zwei Stufen, beide **pro Universe-Projekt** und für genau eine Plattform (Ninox oder React).

| Paket | Preis (netto) | Enthalten |
|---|---|---|
| Free | 0 € | Alle Mini-Widgets, produktiv nutzbar |
| Ultimate | 750 €, einmalig | Alle Premium-Widgets und Mini-Widgets, inklusive Widgets, die nach dem Kauf dazukommen |

Ultimate ist ein Einmalkauf. Du erhältst **Lifetime-Updates**: neue Versionen, Fixes und künftige Premium-Widgets ohne weitere Zahlung.

<!-- host:ninox -->
Der erzeugte Build-Code bleibt in deinem Ninox-Projekt nutzbar.
<!-- /host -->

<!-- host:react -->
Das npm-Paket und die Lifetime-Updates bleiben in deiner React-App nutzbar.
<!-- /host -->

<!-- host:vue -->
Das npm-Paket und die Lifetime-Updates bleiben in deiner Vue-App nutzbar.
<!-- /host -->

Im Paket steckt **eine Produktions-Umgebung**. Entwicklung (`localhost`) und nicht-produktive Stages sind frei.

<!-- host:ninox -->
Weitere Produktions-URLs oder Team-IDs buchst du als Add-on oder lässt sie von uns freischalten.
<!-- /host -->

<!-- host:react -->
Weitere Produktions-Domains buchst du als Add-on oder lässt sie von uns freischalten.
<!-- /host -->

<!-- host:vue -->
Weitere Produktions-Domains buchst du als Add-on oder lässt sie von uns freischalten.
<!-- /host -->

Du kannst den gesamten Katalog vorher nutzen. Ohne Ultimate erscheint in der Produktion bei Premium-Widgets ein Lizenzhinweis — die Oberfläche bleibt bedienbar.

Ninox und React sind zwei Projekte. Wer beide Plattformen produktiv ohne Hinweis nutzen will, kauft Ultimate zweimal.

Aktueller Preis und Checkout: [Preisseite](/pricing). Wie Projekt und Umgebung zusammenhängen: [Buchung und Teamstruktur](/docs/faq/wie-funktioniert-die-buchung-pro-team-und-was-muss-ich-zur-teamstruktur-wissen).


---

# Wie funktioniert die Buchung pro Team und was muss ich zur Teamstruktur wissen?

Source: https://www.arc-rider.com/docs/faq/wie-funktioniert-die-buchung-pro-team-und-was-muss-ich-zur-teamstruktur-wissen


# Wie funktioniert die Buchung pro Team und was muss ich zur Teamstruktur wissen?

Du buchst **pro Universe-Projekt**. Ein Projekt gehört einer Plattform.

<!-- host:ninox -->
Darin liegen Builds, Lizenz und die Produktions-Umgebungen.
<!-- /host -->

<!-- host:react -->
Darin liegen Lizenz und die Produktions-Domains.
<!-- /host -->

<!-- host:vue -->
Darin liegen Lizenz und die Produktions-Domains.
<!-- /host -->

Ultimate enthält **eine Produktions-Umgebung**. Entwicklung und Staging sind frei. Weitere Produktions-Umgebungen sind ein Add-on.

<!-- host:ninox -->
## Ninox: was als Produktions-Umgebung zählt

- **Private Cloud:** die genaue URL, zum Beispiel `https://firma.ninoxdb.de`.
- **On-Premise:** eure Installations-URL, inklusive Subdomains.
- **Public Cloud:** die **Team-ID**. Sie steht in der Ninox-URL nach `/teams/` oder kommt aus der Formel `teamId()`. Ohne hinterlegte Team-ID erscheint der Lizenzhinweis.

Innerhalb einer hinterlegten Umgebung darfst du die Widgets in allen Datenbanken dieses Teams nutzen.

### Eigenes Team

Ein Universe-Projekt, Ultimate einmal, Team-ID oder Private-Cloud-URL hinterlegen.

### Kundenprojekte

Pro Endkunde ein eigenes Universe-Projekt mit eigenem Package. So bleiben Lizenz und Build getrennt. Siehe [Widget-Partner](/docs/faq/was-ist-ein-widget-partner-und-welche-vorteile-habe-ich-davon).

### Dieselbe Lösung für mehrere Mandanten

Jeder produktive Lizenzkontext braucht ein eigenes Projekt — oder zusätzliche Produktions-URLs bzw. Team-IDs im selben Projekt.
<!-- /host -->

<!-- host:react -->
## React

Eine hinterlegte Domain gilt für die Domain selbst und alle Subdomains (`kunde.de` schließt `app.kunde.de` ein). Eine Produktions-Domain steckt im Ultimate-Paket.

Für Kundenprojekte gilt: pro Endkunde ein eigenes Universe-Projekt. Siehe [Widget-Partner](/docs/faq/was-ist-ein-widget-partner-und-welche-vorteile-habe-ich-davon).
<!-- /host -->

<!-- host:vue -->
## Vue

Eine hinterlegte Domain gilt für die Domain selbst und alle Subdomains (`kunde.de` schließt `app.kunde.de` ein). Eine Produktions-Domain steckt im Ultimate-Paket.

Für Kundenprojekte gilt: pro Endkunde ein eigenes Universe-Projekt. Siehe [Widget-Partner](/docs/faq/was-ist-ein-widget-partner-und-welche-vorteile-habe-ich-davon).
<!-- /host -->

Preise: [Wie berechnen sich die Preise?](/docs/faq/wie-sich-preise-zusammensetzen). Fragen zur Struktur: [support@arc-rider.com](mailto:support@arc-rider.com).


---

# Wie verwalte ich mehrere Umgebungen oder URLs?

Source: https://www.arc-rider.com/docs/faq/mehrere-umgebungen-und-urls


<!-- host:react -->
# Mehrere React-Umgebungen

Das Ultimate-Modell gilt pro Universe-Projekt mit einer Produktions-Umgebung; weitere produktive Umgebungen können als Add-on zugeordnet werden. Für React wird die Live-Domain im Projekt hinterlegt.

## Domain und technische Freischaltung

Die Domain-Zuordnung im Portal und die Aktivierung im npm-Paket müssen zusammenpassen. Das Paket liest diese Zuordnung nicht automatisch aus dem Portal. Prüfe Hauptdomain, verwendete Subdomains und öffentlich erreichbare Test-Domains mit der bereitgestellten Aktivierung.

## Entwicklung und Staging

Lokale Entwicklung auf `localhost` oder `127.0.0.1` zeigt keinen Hinweis. Eine im Portal als Entwicklung gekennzeichnete öffentliche Domain wird im npm-Paket nicht automatisch als solche erkannt.

[React-Paket und Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung) · [Vertragsbedingungen](/terms).
<!-- /host -->

<!-- host:ninox -->
# Wie verwalte ich mehrere Umgebungen oder URLs?

Jedes Ultimate-Paket gilt pro Universe-Projekt und schaltet standardmäßig **eine Produktions-Umgebung** frei.

## Welche Umgebungen sind immer kostenlos?

Entwicklungs- und Testumgebungen verbrauchen **kein** Kontingent:

- Lokale Adressen wie `localhost`, `127.0.0.1` oder `::1`.
- Nicht-produktive Staging- und Test-Umgebungen (in Universe als "dev" gekennzeichnet).

## Was zählt als eine Produktions-Umgebung?


Die Lizenz-Einheit hängt vom Ninox-Hosting ab:

- **Private Cloud:** die exakte Subdomain (z. B. `firma.ninoxdb.de`).
- **On-Premise:** die Installations-URL des Servers (inklusive aller Subdomains).
- **Public Cloud:** die **Team-ID** deines Ninox-Teams. Innerhalb dieses Teams können Widgets in beliebig vielen Datenbanken genutzt werden.


## Wie füge ich weitere Produktions-Umgebungen hinzu?

Wenn die Anwendung auf mehreren getrennten Live-Systemen laufen soll:

1. **Add-ons:** zusätzliche Produktions-Umgebungen im Universe-Portal gegen eine Einmalzahlung.
2. **Freischaltung (Kulanz):** wir können zusätzliche Umgebungen im Administrationsbereich kostenlos freischalten, zum Beispiel für interne Testsysteme oder Partner-Szenarien.

Mehr Details zum Lizenzmodell findest du in unseren [AGB](/terms) unter Teil III.
<!-- /host -->

<!-- host:vue -->
# Wie verwalte ich mehrere Umgebungen oder URLs?

Jedes Ultimate-Paket gilt pro Universe-Projekt und schaltet standardmäßig **eine Produktions-Umgebung** frei.

## Welche Umgebungen sind immer kostenlos?

Entwicklungs- und Testumgebungen verbrauchen **kein** Kontingent:

- Lokale Adressen wie `localhost`, `127.0.0.1` oder `::1`.
- Nicht-produktive Staging- und Test-Umgebungen (in Universe als "dev" gekennzeichnet).

## Was zählt als eine Produktions-Umgebung?


**Vue:** Eine hinterlegte Live-Domain. Sie deckt die Hauptdomain und **sämtliche Subdomains** ab (`firma.de` lizenziert auch `app.firma.de`).


## Wie füge ich weitere Produktions-Umgebungen hinzu?

Wenn die Anwendung auf mehreren getrennten Live-Systemen laufen soll:

1. **Add-ons:** zusätzliche Produktions-Umgebungen im Universe-Portal gegen eine Einmalzahlung.
2. **Freischaltung (Kulanz):** wir können zusätzliche Umgebungen im Administrationsbereich kostenlos freischalten, zum Beispiel für interne Testsysteme oder Partner-Szenarien.

Mehr Details zum Lizenzmodell findest du in unseren [AGB](/terms) unter Teil III.
<!-- /host -->


---

# Action Polling

Source: https://www.arc-rider.com/docs/patterns/action-polling


# Action Polling (`polling` auf `update`)

## AI Defaults (read first)

- **`polling` nur auf `type: "update"`** — wiederholt dasselbe Feld-Update in Intervallen (typisch: Trigger-Feld).
- **API-Calls gehören in den Ninox-Trigger** („Nach Änderung“), nicht ins Widget. Kein CORS-Thema.
- **Stopp:** Formel-Boolean `active` (Live über Widget-Reload) **und** `maxAttempts` als Sicherheitsnetz.
- **Loading** (Button/Layout) bleibt an, solange `perform` läuft — inkl. Poll-Dauer. Status-Texte: `loading.overlay.sequences` + `when:`.
- **Trigger-Feld zurücksetzen** am Ende des Triggers (`false` / `null`), sonst feuert „Nach Änderung“ bei erneutem `true` oft nicht.

---

## Problem

Nach einem Klick soll Ninox eine API prüfen oder ein Skript erneut ausführen, **solange** ein Job noch läuft — ohne dass der Browser die API direkt aufruft.

## Lösung

`update` mit `polling`: das Widget schreibt das Trigger-Feld wiederholt; der Trigger macht `http(...)` / Logik und schreibt den Status (z. B. in ein Data-Bag-Feld). Die Formel setzt `active` aus diesem Status.

```javascript
let state := parseJSON(text(helper_uiState));
let pollActive := state.jobStatus = "running";

actions: [{
	type: "update",
	recordId: Nr,
	fieldId: fieldId(Nr, "trigger_checkApi"),
	value: true,
	polling: {
		intervalMs: 2000,
		maxAttempts: 30,
		active: pollActive
	}
}]
```

| Feld | Default | Bedeutung |
|------|---------|-----------|
| `intervalMs` | `2000` | Pause zwischen Updates (ms) |
| `maxAttempts` | `30` | Max. Updates inkl. dem ersten |
| `active` | `true` | Poll weiter, solange `true`; Formel-Boolean (z. B. aus Data Bag) |

**Ablauf:** erstes Update → warten → wenn Live-`active` noch `true` und Attempts nicht erreicht → erneut Update → … → Stopp → Loading aus.

## Live-`active` (Button / Layout)

Bei Formel-Reload nach dem Trigger rufen Button und Layout `syncPollingGates` auf. So sieht die laufende Poll-Schleife den neuen Boolean — nicht nur den Snapshot vom Klick.

Ohne Sync (andere Widgets): Snapshot + `maxAttempts` gelten weiterhin.

## Zusammenspiel mit Loading / Sequences

```javascript
loading: {
	show: true,
	overlay: {
		title: "Bitte warten…",
		sequences: [
			{ after: 0, title: "Starte…", priority: 5 },
			{ when: pollActive, title: "API prüft…", priority: 40 }
		]
	}
}
```

`when` und `polling.active` können denselben Boolean nutzen.

## Trigger-Muster (Ninox)

1. Ja/Nein-Feld z. B. `trigger_checkApi`
2. Trigger „Nach Änderung“: wenn `true` → HTTP / Logik → Status ins Bag schreiben → `trigger_checkApi := false`
3. Widget pollt mit `value: true` und `active` aus dem Status

## Lokaler Smoke-Test (Interactive)

1. `npm start` im Widgets-Repo
2. Sidebar → **Button** → Variante **★ Polling Test (Console)** (oder P1–P3)
3. DevTools-Console filtern: `[arc-polling]`
4. Erwartung:
   - **Poll until active=false** — 3× `database.update`, dann Log `active=false`, Poll stoppt
   - **maxAttempts=3** — genau 3 Updates
   - **Single update** — genau 1 Update

## Grenzen

- Läuft nur solange der Tab / die Ansicht offen ist (kein echter Cron).
- v1: nur `type: "update"`; Live-Gate-Sync: arcCustomButton + arcCustomLayout.


---

# Data Bag Actions

Source: https://www.arc-rider.com/docs/patterns/data-bag-actions


# Data Bag Actions (partielle Updates in JSON-Töpfen)

## AI Defaults (read first)

- **`createNew.dataBag`** (Calendar Week) = nach erfolgreichem Anlegen, inkl. `##newRecordId##`. Siehe [`custom-calendar-week`](../widgets/custom-calendar-week.md).
- **Gilt für alle Widgets mit `actions`**, die den Ninox Action Performer nutzen (Button, Layout, Table, KPI Bar, Calendar, Drawing, …).
- **Syntax:** `dataBag: { encoding, base, patch }` — `patch` folgt JSON Merge Patch (RFC 7386): Key setzen/überschreiben; `null` / `''` löscht den Key.
- **`encoding`:** `"raw"` (Default) — Plain-JSON im Textfeld via `JSON.stringify` / `parseJSON`. **`encoding` weglassen**, wenn nicht Legacy-Daten.
- **`base`:** aktueller Feldwert (Rohstring aus dem Textfeld oder bereits geparstes Objekt).
- **Lesen in Formeln:** `parseJSON(text(helper_uiState))` bzw. `parseJSON(helper_data)` — **ohne** `urlDecode`.
- **Alternative:** plain `value` auf der Action, wenn das Zielfeld nur einen einzelnen Wert hält.
- **Legacy:** `"urlEncoded"` nur bei bestehenden url-kodierten Feldern (`parseJSON(urlDecode(...))`). Siehe Abschnitt unten.
- **Nicht verwechseln:** Widget-Prop `dataBag: { key, encoding }` in **arcCustomDrawing** — nur für Shape-Geometrie in verschachtelten JSON-Töpfen. Siehe [`custom-drawing`](../widgets/custom-drawing.md#-databag).

---

## Problem

Viele UI-Zustände (Tab, Filter, ausgewählte ID) liegen in **einem** JSON-Textfeld (State-Bag). Beim Klick soll nur **ein Key** geändert werden — ohne den Rest zu löschen.

Ohne `dataBag` musst du in Ninox den Topf manuell lesen, `setItem` aufrufen und wieder serialisieren (siehe [State-Bag in einem Textfeld](/docs/templates/tips_statefield)).

Mit **`dataBag` auf der Action** übernimmt der Action Performer Read → Patch → Write.

## Action-Syntax

### Partiell patchen (empfohlen für State-Bags)

```javascript
{
  type: "update",
  recordId: Nr,
  fieldId: fieldId(Nr, "helper_mainContentState"),
  dataBag: {
    base: helper_mainContentState,
    patch: { selectedShape: "123", activeTab: "details" }
  }
}
```

- **`base`:** Rohwert aus dem Feld (String oder bereits geparstes Objekt — der Helfer normalisiert).
- **`patch`:** nur die Keys, die sich ändern sollen.
- Key löschen: `patch: { statusFilter: null }` oder `""`.
- **`encoding`:** optional; Default `"raw"` — Plain-JSON im Textfeld.

### Einfacher Wert (dediziertes Feld)

```javascript
{
  type: "update",
  recordId: Nr,
  fieldId: fieldId(Nr, "helper_selectedId"),
  value: "123"
}
```

## Wo funktioniert das?

| Kontext | `dataBag` auf Action | Widget-`dataBag` (`key`) |
|--------|----------------------|---------------------------|
| arcCustomButton, Table, KPI Bar, Calendar, Input, … | ja (`update` + `create`) | — |
| arcCustomCalendarWeek — `createNew` | ja (`create`, inkl. `##newRecordId##`) | — |
| arcCustomLayout — Block-`actions` (Klick) | ja (`update` + `create`) | — |
| arcCustomLayout — Widget-`actions` (Klick auf gesamtes Layout) | ja (`update` + `create`) | — |
| arcCustomDrawing — Shape-`actions` (Klick) | ja (`update`) | — |
| arcCustomDrawing — Geometrie speichern | — | ja (`key` + optional `encoding`) |

Alle Widgets teilen sich dieselbe Action-Engine für `update` und `create` (inklusive `dataBag`).

> **Hinweis für arcCustomDrawing Create:** Das Drawing-Widget legt neue Shapes über einen eigenen Create-Pfad an, nicht über die üblichen `actions`. Dort gilt weiterhin `setNewRecordId`. `dataBag` auf `type: "create"` gilt nur für explizit definierte Create-Actions in anderen Widgets (z. B. Button, Layout).

**React / Vue / WeWeb:** Actions werden an den Host durchgereicht (`onAction` / `emit('action')`). `dataBag`-Patching ist dort nicht automatisch — der Host muss den Patch selbst anwenden oder den Klartext-`value` nutzen.

## `dataBag` auf `create`-Actions

Neu: `dataBag` funktioniert auch auf `type: "create"`. Nach dem Anlegen des Datensatzes wird der Platzhalter `##newRecordId##` durch die numerische ID des neuen Records ersetzt — dann wird der Bag gepatch und ins Zielfeld geschrieben.

### Platzhalter `##newRecordId##`

Ersetzt in beliebiger Tiefe (Strings, Objekte, Arrays) die neue numerische Record-ID nach dem Create.

```javascript
{
  type: "create",
  tableId: tableId("Aufgaben"),
  changeFieldValues: [{
    fieldId: fieldId("Aufgaben", "Projekt"),
    value: Nr
  }],
  dataBag: {
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_uiState"),
    base: helper_uiState,
    patch: { selectedTaskId: "##newRecordId##" }
  }
}
```

**Ablauf:** Create → neue ID → `##newRecordId##` auflösen → `readBag(base)` → `applyPatch(bag, patch)` → `writeBag` → `database.update`

### Mehrere Bags nach Create (Array)

```javascript
dataBag: [
  {
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_uiState"),
    base: helper_uiState,
    patch: { selectedTaskId: "##newRecordId##", activeTab: "details" }
  },
  {
    recordId: parentNr,
    fieldId: fieldId(parentNr, "helper_dashState"),
    base: helper_dashState,
    patch: { lastCreatedId: "##newRecordId##" }
  }
]
```

### Kombiniert mit `setNewRecordId`

Beide Mechanismen können zusammen genutzt werden:

| | `setNewRecordId` | `dataBag` auf Create |
|---|---|---|
| **Zielfeld** | Ninox-Referenzfeld (Verknüpfung) | JSON-Textfeld (State-Bag) |
| **Schreibt** | numerische ID direkt | ID als Patch-Key in JSON |
| **Wann** | Parent-Datensatz verlinken | UI-State nach Create setzen |

```javascript
{
  type: "create",
  tableId: tableId("Aufgaben"),
  changeFieldValues: [...],
  setNewRecordId: [{ recordId: Nr, fieldId: fieldId(Nr, "LetzteAufgabe") }],
  dataBag: {
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_uiState"),
    base: helper_uiState,
    patch: { selectedTaskId: "##newRecordId##" }
  }
}
```

### Kalender `createNew` (nach erfolgreichem Anlegen)

`createNew.dataBag` hängt direkt am Kalender-Create, nicht an einer Button-Action. Nach dem Anlegen (Aufziehen, Ganztags oder Ghost-Klick) läuft derselbe Create-Pfad. Typisch: Auswahl leeren, damit der Placement-Ghost verschwindet.

```javascript
createNew: {
  tableId: tableId("Termine"),
  dateFrom: fieldId(first(Termine), "Datum von"),
  timeFrom: fieldId(first(Termine), "Von"),
  dateTo: fieldId(first(Termine), "Datum bis"),
  timeTo: fieldId(first(Termine), "Bis"),
  dataBag: {
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_uiState"),
    base: helper_uiState,
    patch: { auswahlId: null, lastTerminId: "##newRecordId##" }
  }
}
```

## Beispiele

### Tab wechseln (Button)

```javascript
arcCustomButton({
  uniqueId: "tab-details-" + Nr,
  title: "Details",
  actions: [{
    type: "update",
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_uiState"),
    dataBag: {
      base: helper_uiState,
      patch: { activeTab: "details" }
    }
  }]
})
```

### Mobile Dimmer schließen (Layout-Block)

```javascript
blocks: [{
  width: "100%", height: "100%",
  styles: "position: absolute; z-index: 100;",
  value: "",
  actions: [{
    type: "update",
    recordId: Nr,
    fieldId: fieldId(Nr, "helper_mainContentState"),
    dataBag: {
      base: helper_mainContentState,
      patch: { sidebarOpen: "", selectedShape: "" }
    }
  }]
}]
```

### Shape auswählen → Sidebar (Drawing)

```javascript
actions: [{
  type: "update",
  recordId: stateRecordId,
  fieldId: stateField,
  dataBag: {
    base: helper_mainContentState,
    patch: { selectedShape: Nr }
  }
}]
```

Ausführlich: [`custom-drawing`](../widgets/custom-drawing.md) (Shape-`actions`, Klick vs. Drag).

## Legacy: `urlEncoded`

Früher wurde JSON oft mit `urlEncode(formatJSON(...))` geschrieben, weil Ninox-Actions mit `{}` in `value` problematisch waren. Mit **dataBag** (Patch im Bundle) ist das in **neuen Projekten nicht mehr nötig**.

| | `raw` (Default) | `urlEncoded` (Legacy) |
|---|---|---|
| Im Feld | `{"activeTab":"details"}` | `%7B%22activeTab%22%3A...` |
| Formel lesen | `parseJSON(text(feld))` | `parseJSON(urlDecode(text(feld)))` |
| Action schreiben | `dataBag: { base, patch }` | zusätzlich `encoding: "urlEncoded"` |
| Wann | neue Demos, Seeds, Trigger | bestehende Kundendaten |

## Siehe auch

- [State-Bag in einem Textfeld](/docs/templates/tips_statefield) — State-Bag manuell mit Ninox `setItem` / `item`
- [`custom-drawing`](../widgets/custom-drawing.md) — Widget-`dataBag` für Pin-Geometrie + Shape-Actions


---

# Datum und Zeit in React

Source: https://www.arc-rider.com/docs/patterns/react-dates


# Datum und Zeit in React

Die Kalender verwenden getrennte Werte für Kalendertage und Uhrzeiten. Das verhindert, dass eine Anzeige versehentlich einen Unix-Zeitstempel als Uhrzeit interpretiert.

## Kalendertag

`dateFrom`, `dateTo` und ein datumsbasierter `startDate` erhalten Millisekunden seit dem Unix-Epoch. Die Beispiele erzeugen den Tageswert mit `new Date(2026, 8, 17).getTime()`: September hat im JavaScript-Konstruktor den Index `8`.

Für Calendar Grid ist `dateSettings.month` dagegen einsbasiert: September ist `9`.

## Uhrzeit und Dauer

`timeFrom` und `timeTo` sind Millisekunden seit Tagesbeginn: `9 * 60 * 60 * 1000` steht für 09:00 Uhr. Eine Stunde Dauer ist `60 * 60 * 1000`.

Calendar Week verwendet für den sichtbaren Bereich `timeSettings.timeStart` und `timeSettings.duration` in derselben Einheit. `dateSettings.duration` zählt dagegen Tage.

## Zeitzonen

Lege in deiner Anwendung fest, ob deine Daten lokale Kalendertage oder globale Zeitpunkte darstellen. Konvertiere Backend-Zeitpunkte vor der Übergabe in die gewünschte Anzeigezone. Die Beispiele verwenden lokal erzeugte Tageswerte und `timeZoneBalance: 0`. Eine feste Stundenkorrektur bildet keine vollständige Zeitzone mit Sommerzeitwechseln ab.

Teste besonders Termine um Mitternacht und an Zeitumstellungen. Lokale Datumsstrings wie `17.09.2026` eignen sich zur Anzeige, nicht als Datenaustauschformat.

## Bearbeiten und speichern

Für verlässliche Speicherung benutzt das [Kalender-Beispiel](/docs/react/examples/individuelles-design-in-der-calendarweek) ein Formular und neue State-Werte. Die vorhandenen Drag-Callbacks melden den ursprünglichen Stand, aber nicht alle neuen Zielzeiten. Deshalb bleiben die dokumentierten Kalenderbeispiele ohne Drag & Drop.


---

# Logbook to Billing

Source: https://www.arc-rider.com/docs/patterns/logbook-to-billing


# Logbook to Billing (Zeiterfassung → Aufwandsberechnung)

## AI Defaults (read first)

- **Zwei getrennte Konzepte:** `TimeEntry` (einzelner Zeiteintrag) und `BillingPeriod` (Abrechnungszeitraum mit Soll-Stunden/Budget). Nicht vermischen.
- **`billingMode` pro Zeiteintrag** entscheidet den Ausgabepfad: `contingent` (zählt auf ein Kontingent), `billable_extra` (wird separat abgerechnet), `non_billable` (zählt nirgends).
- **Zwei Ausgabepfade, kein Automatismus dazwischen:** Stunden-Abrechnung (→ Rechnungsposition) und Budget/Kontingent-Nachweis (→ Aufwandsposition) sind unabhängige Auswertungen auf denselben `TimeEntry`-Daten — nicht ein einziger kombinierter Bericht.
- **Kennzahlen sind reine Aggregationen** (`sum`, `min`, `round`) auf gefilterten `TimeEntry`-Listen — kein separates Aggregat-Objekt in der Datenbank nötig, kann pro Abfrage berechnet werden.
- **Texte sind Config, kein Hardcoding:** Rechnungs- und Aufwandszeilen entstehen aus Platzhalter-Templates (`invoiceLineTemplate`, `effortLineTemplate`), nicht aus fest verdrahteten Sätzen im Formelcode.
- **Kein lauffähiges Space-Beispiel in diesem Dokument** — nur Konzept, Datenmodell und illustrative Formeln. Konkrete Umsetzung ist projektspezifisch.

---

## Problem

Viele Dienstleistungsverträge laufen nach demselben Muster: Mitarbeitende erfassen Zeiteinträge (Logbuch), und am Ende einer Periode muss daraus entweder

1. eine **Rechnungsposition** werden (Stunden × Satz), oder
2. ein **Aufwandsnachweis** ohne Rechnungsbetrag (wie viel von einem Kontingent/Budget wurde verbraucht).

Ohne ein gemeinsames Datenmodell entsteht das für jedes Projekt neu — mit leicht unterschiedlichen Feldnamen und Formeln, die schwer wiederverwendbar sind.

## Datenmodell

### `TimeEntry` (Logbuch-Zeile)

| Feld | Typ | Bedeutung |
|------|-----|-----------|
| `start` / `end` | Datum/Zeit | Beginn/Ende des Zeiteintrags |
| `durationHours` | Zahl (berechnet) | `(end - start) / 3600000` |
| `employeeRef` | Referenz | Mitarbeiter:in |
| `contractRef` | Referenz | Zugehöriger Vertrag/Kunde |
| `locationType` | Enum | `onsite` \| `office` \| `remote` |
| `activityLabel` | Text | Freitext oder Kategorie der Tätigkeit |
| `billingMode` | Enum | `contingent` \| `billable_extra` \| `non_billable` |
| `billedAt` | Datum (optional) | Gesetzt, sobald der Eintrag abgerechnet wurde |

### `BillingPeriod` (Abrechnungszeitraum)

| Feld | Typ | Bedeutung |
|------|-----|-----------|
| `contractRef` | Referenz | Zugehöriger Vertrag/Kunde |
| `periodStart` / `periodEnd` | Datum | Grenzen des Zeitraums (z. B. Kalenderjahr, Quartal, Vertragslaufzeit) |
| `targetHours` | Zahl | Soll-Stunden für den Zeitraum |
| `hourlyRate` | Zahl | Stundensatz |
| `budgetAmount` | Zahl (optional) | Alternativ zu `targetHours`, wenn in Geld statt Stunden budgetiert wird |

## Formeln (illustrativ)

```javascript
let actualHours := sum(
    (select TimeEntry where
        contractRef = period.contractRef
        and billingMode = "contingent"
        and start >= period.periodStart
        and start <= period.periodEnd
    ).durationHours
);

let remainingHours := period.targetHours - actualHours;

let progressPercent := min(100, round(actualHours / period.targetHours * 100));

let billableQueue := (select TimeEntry where
    contractRef = period.contractRef
    and billingMode = "billable_extra"
    and billedAt = null
);
```

## Zwei Ausgabepfade

### 1. Stunden-Abrechnung → Rechnungsposition

Für Zeiteinträge mit `billingMode = "billable_extra"` und `billedAt = null`:

1. `billableQueue` gruppieren (z. B. nach Periode + `activityLabel`)
2. Pro Gruppe: `lineAmount := sum(durationHours) * hourlyRate`
3. Zeilentext aus `invoiceLineTemplate` (siehe Textbaustein-Mechanismus)
4. Nach Übernahme in die Rechnung: `billedAt` auf allen enthaltenen Zeiteinträgen setzen

### 2. Budget/Kontingent → Aufwandsposition

Kein Rechnungsbetrag, sondern ein **Statusnachweis** pro `BillingPeriod`:

- `actualHours`, `targetHours`, `remainingHours`, `progressPercent`
- Zeilentext aus `effortLineTemplate`
- Typische Darstellung: `arcCustomProgressBar` oder `arcCustomKpiBar` für den Fortschritt, `arcCustomTable` für die Liste der Perioden/Verträge

## Textbaustein-Mechanismus

Statt fixer Sätze im Formelcode ein Config-Objekt mit Platzhaltern — der Wortlaut bleibt pro Projekt austauschbar, ohne die Formeln anzufassen:

```javascript
let cfg := {
    labels: { onsite: "Vor Ort", office: "Büro", remote: "Remote" },
    invoiceLineTemplate: "{hours} Std. {activityLabel} ({period}) à {rate} €",
    effortLineTemplate: "{actualHours} von {targetHours} Std. genutzt ({progressPercent} %), Rest {remainingHours} Std."
};
```

Platzhalter werden vor der Ausgabe per einfachem String-Replace aufgelöst (z. B. `replace(cfg.invoiceLineTemplate, "{hours}", text(hours))` verkettet für jeden Platzhalter).

## Beispiele

### Fortschrittsanzeige für ein Kontingent

```javascript
arcCustomProgressBar({
    uniqueId: "contingent-progress-" + period.Nr,
    value: progressPercent,
    label: replace(
        replace(cfg.effortLineTemplate, "{actualHours}", text(actualHours)),
        "{targetHours}", text(period.targetHours)
    )
})
```

### Offene abrechenbare Stunden als Tabelle

```javascript
arcCustomTable({
    uniqueId: "billable-queue-" + contractRef.Nr,
    table: [
        {
            columns: [
                { value: activityLabel },
                { value: text(durationHours) + " Std." },
                { value: text(durationHours * hourlyRate) + " €" }
            ]
        }
        // ... eine Zeile pro Eintrag aus billableQueue, gruppiert
    ]
})
```

## Siehe auch

- [`data-bag-actions`](./data-bag-actions.md) — partielle Updates, falls Filter/Auswahl-Zustand pro Periode zwischengespeichert wird
- `docs/widgets/custom-kpi-bar.md`, `docs/widgets/custom-progress-bar.md` — Fortschritts-/Kennzahlen-Darstellung
- `docs/widgets/custom-table.md` — Listendarstellung für Zeiteinträge/Rechnungspositionen


---

# Nested Widget Descriptors

Source: https://www.arc-rider.com/docs/patterns/nested-widget-descriptors


<!-- host:react -->
# Inhalte und Widgets in React kombinieren

In unterstützten `ArcWidgetSlot`-Feldern kannst du Text, ein JSX-Element oder einen Widget-Deskriptor verwenden. Für React-Anwendungen ist JSX praktisch: Props, Typprüfung und Event-Callbacks bleiben direkt an der Komponente.

## JSX und eigene Callbacks

<!-- react-example: layout-01-form_numbers.tsx -->
```tsx
import {
  ArcWidgetBadge,
  ArcWidgetInput,
  ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';

const row = (number: string, title: string) => ({
  value: (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        gap: '12px',
        height: '48px',
        blocks: [
          {
            width: '52px',
            value: (
              <ArcWidgetBadge
                data={{
                  value: number,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
          {
            width: 'fraction',
            value: (
              <ArcWidgetInput
                data={{
                  type: 'number',
                  labelSettings: { title },
                  numpad: { suffix: '€' },
                }}
              />
            ),
          },
        ],
      }}
    />
  ),
});

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        gap: '8px',
        width: '420px',
        blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')],
      }}
    />
  );
}
```

`blocks[].value` gehört zu den unterstützten Slots. Weitere Beispiele sind Tabellenzellen und Karteninhalte. Ein Fragment fasst mehrere React-Inhalte zu einem Element zusammen. Slideshow unterstützt aktuell ausschließlich String-Inhalte.

## Deklarative Deskriptoren

Ein Deskriptor besteht aus `widget`, optionaler stabiler `id` und `data`. `widget` verwendet den registrierten Namen wie `arc-widget-button`.

```tsx
import { useState } from 'react';
import { ArcWidgetLayout } from '@arcrider/arcwidgets-react';
export default function Example() {
  const [message, setMessage] = useState('Ready');
  return (
    <>
      <ArcWidgetLayout
        data={{
          direction: 'horizontal',
          width: '100%',
          height: '70px',
          blocks: [
            {
              width: 'fraction',
              value: {
                widget: 'arc-widget-button',
                id: 'descriptor-button',
                data: {
                  title: 'Trigger',
                },
              },
            },
          ],
        }}
        onAction={(type) => {
          if (type === 'click') setMessage('Button clicked');
        }}
      />
      <p role="status">{message}</p>
    </>
  );
}
```

Der Deskriptor nutzt hier den geerbten Event-Fallback des Layouts. Wenn mehrere interaktive Kinder unterschiedliche Aktionen auslösen sollen, verwende JSX mit eigenen Callback-Props.

## Inhalte aus fremden Quellen

String-Slots können HTML interpretieren. Gib fremde Texte daher über JSX aus, etwa als Textinhalt eines `span`. Verwende HTML nur aus eigener oder zuvor bereinigter Quelle. Deskriptor-Konfigurationen sind kein Ersatz für die Validierung fremder Daten.

[Table mit Mini-Widgets](/docs/react/examples/custom-table-mit-mini-widgets) · [Dashboard](/docs/react/examples/dashboardansicht-mit-grid).
<!-- /host -->

<!-- host:ninox -->
# Nested Widget Descriptors (Object-Notation)

## AI Defaults (read first)


- **Top-level** Ninox formula: use **`arcCustomLayout({ uniqueId: … })`** (function call) — not a descriptor object.
- **Nested** inside another widget's content slot (`blocks[].value`, table cells, drawing sidebar, kanban cards, …): use **`{ widget, uid, data }`**.
- **`widget`**: internal kebab-case ID (e.g. `"arc-widget-layout"`), **not** `arcCustomLayout`.
- **`uid`**: same rules as `uniqueId` — unique, no spaces/special characters.
- **`data`**: same properties as the function call; use `uid` at the top level instead of `uniqueId` inside `data`.
- **Next-Gen only**: parent **and** child must come from the current **`bundle.js` / profile build** (`arcWidgetManager` v3). **Legacy Ninox-formula widgets do not support this.**
- When unsure whether a widget is Next-Gen: if it only exists as an old Ninox template formula (not in the bundle), use the function call or plain HTML — **never** a descriptor object.


---

# Verschachtelte Widgets als JSON-Objekt

Mini-Widgets und andere Widgets sitzen in Slots als **reines JSON-Objekt** — nicht als vorgerendertes HTML.

Das ist nützlich in Layout-Blöcken, Tabellen-Zellen, Drawing-Sidebars und tief verschachtelten Oberflächen.

## Zwei Schreibweisen


### Top-Level (Ninox-Formelfeld)

Der Einstieg bleibt ein **Funktionsaufruf**:

```javascript
arcCustomLayout({
    uniqueId: "dashboard-" + Nr,
    embedded: false,
    fullscreen: true,
    height: "100%",
    direction: "vertical",
    blocks: [ … ]
})
```


### Verschachtelt (Inhalt in einem Slot)

In `blocks[].value` (und vergleichbaren Slots) nutzt du die **Widget-Descriptor-Notation**:

```javascript
{
    widget: "arc-widget-button",
    uniqueId: "open-btn-" + Nr,   // oder kurz: uid: "open-btn-" + Nr
    data: {
        title: "Öffnen",
        height: "20px",
        width: "auto",
        actions: [{ type: "popup", recordId: "42" }]
    }
}
```

Für die ID akzeptiert der Descriptor **beide Schreibweisen** gleichwertig:
- `uniqueId` — konsistent mit der Root-Config
- `uid` — Kurzform, ebenfalls gültig

### Mapping


| Funktionsaufruf | Descriptor |
|-----------------|------------|
| `arcCustomLayout({ … })` | `widget: "arc-widget-layout"` |
| `uniqueId: "…"` | `uniqueId: "…"` oder `uid: "…"` (top-level, **nicht** in `data`) |
| Alle anderen Props | In `data: { … }` |


## Vollständiges Beispiel (Layout → Button)

Siehe auch [Custom Layout](/docs/widgets/custom-layout) für verschachtelte Layout-Blöcke.

```javascript
{
    widget: "arc-widget-layout",
    uniqueId: "sidebar-item-" + Nr,   // uid: "sidebar-item-" + Nr wäre gleichwertig
    data: {
        embedded: true,
        direction: "horizontal",
        gap: "10px",
        blocks: [{
            width: "fraction",
            height: "auto",
            value: "Mangel ID"
        }, {
            width: "auto",
            height: "auto",
            value: {
                widget: "arc-widget-button",
                uniqueId: "open-btn-" + Nr,   // uid: "open-btn-" + Nr wäre gleichwertig
                data: {
                    title: "Öffnen",
                    height: "20px",
                    actions: [{ type: "popup", recordId: "42" }]
                }
            }
        }]
    }
}
```


In Ninox bleibt `uniqueId: "sidebar-item-" + Nr` üblich, und `recordId: Nr` in Actions.

## Voraussetzung: Next-Gen-Bundle

Die Engine erkennt Descriptor-Objekte in Slots über **`append_content`**: Ist `value` ein Objekt mit Feld `widget`, ruft sie `arcWidgetManager.js(widget, uid, data)` auf.

Das funktioniert **nur**, wenn:

1. Das **Parent-Widget** aus dem aktuellen Bundle kommt und den Slot über `append_content` rendert.
2. Das **Child-Widget** im selben Bundle **registriert** ist.

### Next-Gen (funktioniert)

- Widgets, die im aktuellen Bundle / Ninox-Template registriert sind

### Legacy (funktioniert **nicht**)

- Widget existiert **nur** als alte **NinoxScript-Formel** im Template / in der Datenbank (HTML-String, kein `arcWidgetManager`)
- Slot erwartet fertiges HTML oder ein Formel-Ergebnis — `{ widget: … }` wird nicht interpretiert (leer, Konsole-Fehler oder kaputtes Markup)

**Noch ohne Descriptor-Unterstützung:** `arcCheckBox`, `shortNumbers` — diese **können weder Parent noch Child** in der Descriptor-Notation sein.


## Parent-Widgets mit Descriptor-Slots

Diese Widgets mounten verschachtelte Descriptors (haben `append_content`):

| Widget-ID | Typische Slots |
|-----------|----------------|
| `arc-widget-layout` | `blocks[].value` |
| `arc-widget-button` | `icon`, `title`, `subtitle`, `prefix`, `suffix` |
| `arc-widget-table` | `table[].columns[].value` |
| `arc-widget-drawing` | `sidebarItem`, `rightSideContent`, Shape-Inhalte |
| `arc-widget-kanban` | Karten-`value`, Swimlane-Inhalte |
| `arc-widget-select` | `currentValue`, `items[].title` |
| `arc-widget-input` | Label-/Prefix-Slots |
| `arc-widget-badge` | Badge-Inhalt |
| `arc-widget-upload` | `container.value` |
| `arc-widget-calendar-week` | Entry-Inhalte |
| `arc-widget-calendar-timeline` | Zellen-/Entry-Inhalte |
| `arc-widget-calendar-grid` | Zellen-Inhalte |

## Child-Widgets (häufig verschachtelt)

Alle im Bundle registrierten Widgets können als **`widget`-Wert** erscheinen, z. B.:


| `widget`-Wert | Ninox-Funktion |
|---------------|----------------|
| `arc-widget-layout` | `arcCustomLayout` |
| `arc-widget-button` | `arcCustomButton` |
| `arc-widget-badge` | `arcCustomBadge` |
| `arc-widget-icon` | `arcCustomIcon` |
| `arc-widget-select` | `arcCustomSelect` |
| `arc-widget-input` | `arcCustomInput` |
| `arc-widget-image` | `arcCustomImage` |
| `arc-widget-grid` | `arcCustomGrid` |
| `arc-widget-text` | (Mini-Widget / Text) |

Die **`widget`-ID** steht in der Tabelle oben (`arc-widget-button`, `arc-widget-layout`, …).


## Wann welches Format?


| Situation | Format |
|-----------|--------|
| Root-Widget in Ninox-Formelfeld | `arcCustomXxx({ uniqueId, … })` |
| Inhalt in Layout-Block, Table-Zelle, Drawing-Sidebar, … | `{ widget, uniqueId, data }` oder `{ widget, uid, data }` |
| Legacy-Widget noch nicht im Bundle | Funktionsaufruf oder HTML — **kein** Descriptor |
| Plain Text in Block | String (`value: "Text"`) |


## Fehler vermeiden

- ❌ `widget: "arcCustomLayout"` oder `widget: "ArcWidgetLayout"` — falsche ID (CamelCase)
- ❌ `uniqueId` oder `uid` **innerhalb** von `data` setzen — immer top-level (auf gleicher Ebene wie `widget` und `data`)

- ❌ Descriptor in Top-Level-Formelfeld ohne Parent — use function call
- ❌ Descriptor als Child eines Legacy-Layouts aus altem Ninox-Template


## Siehe auch

- [Custom Layout](/docs/widgets/custom-layout) — Layout-Blocks und `value`-Slots
- [Button](/docs/mini-widgets/buttons) — `prefix` / `suffix` als nested widgets

<!-- /host -->

<!-- host:vue -->
# Nested Widget Descriptors (Object-Notation)

## AI Defaults (read first)


- **Root** in Vue: the `ArcWidget…` component with `:data` and `@action`.
- **Nested** in a slot: `{ widget, uid, data }` inside the parent's `data`.
- **`widget`**: kebab-case ID (`"arc-widget-button"`), not the Vue component name.


---

# Verschachtelte Widgets als JSON-Objekt

Mini-Widgets und andere Widgets sitzen in Slots als **reines JSON-Objekt** — nicht als vorgerendertes HTML.

Das ist nützlich in Layout-Blöcken, Tabellen-Zellen, Drawing-Sidebars und tief verschachtelten Oberflächen.

## Zwei Schreibweisen


### Root (Vue-Komponente)

Der Einstieg ist die Komponente. Nested Descriptors leben **innen** in `data`.


### Verschachtelt (Inhalt in einem Slot)

In `blocks[].value` (und vergleichbaren Slots) nutzt du die **Widget-Descriptor-Notation**:

```javascript
{
    widget: "arc-widget-button",
    uniqueId: "open-btn-" + Nr,   // oder kurz: uid: "open-btn-" + Nr
    data: {
        title: "Öffnen",
        height: "20px",
        width: "auto",
        actions: [{ type: "popup", recordId: "42" }]
    }
}
```

Für die ID akzeptiert der Descriptor **beide Schreibweisen** gleichwertig:
- `uniqueId` — konsistent mit der Root-Config
- `uid` — Kurzform, ebenfalls gültig

### Mapping


| Vue-Komponente | Descriptor |
|----------------|------------|
| `<ArcWidgetLayout … />` | `widget: "arc-widget-layout"` |
| Config-Props | In `data: { … }` |


## Vollständiges Beispiel (Layout → Button)

Siehe auch [Custom Layout](/docs/widgets/custom-layout) für verschachtelte Layout-Blöcke.

```javascript
{
    widget: "arc-widget-layout",
    uniqueId: "sidebar-item-" + Nr,   // uid: "sidebar-item-" + Nr wäre gleichwertig
    data: {
        embedded: true,
        direction: "horizontal",
        gap: "10px",
        blocks: [{
            width: "fraction",
            height: "auto",
            value: "Mangel ID"
        }, {
            width: "auto",
            height: "auto",
            value: {
                widget: "arc-widget-button",
                uniqueId: "open-btn-" + Nr,   // uid: "open-btn-" + Nr wäre gleichwertig
                data: {
                    title: "Öffnen",
                    height: "20px",
                    actions: [{ type: "popup", recordId: "42" }]
                }
            }
        }]
    }
}
```


## Parent-Widgets mit Descriptor-Slots

Diese Widgets mounten verschachtelte Descriptors (haben `append_content`):

| Widget-ID | Typische Slots |
|-----------|----------------|
| `arc-widget-layout` | `blocks[].value` |
| `arc-widget-button` | `icon`, `title`, `subtitle`, `prefix`, `suffix` |
| `arc-widget-table` | `table[].columns[].value` |
| `arc-widget-drawing` | `sidebarItem`, `rightSideContent`, Shape-Inhalte |
| `arc-widget-kanban` | Karten-`value`, Swimlane-Inhalte |
| `arc-widget-select` | `currentValue`, `items[].title` |
| `arc-widget-input` | Label-/Prefix-Slots |
| `arc-widget-badge` | Badge-Inhalt |
| `arc-widget-upload` | `container.value` |
| `arc-widget-calendar-week` | Entry-Inhalte |
| `arc-widget-calendar-timeline` | Zellen-/Entry-Inhalte |
| `arc-widget-calendar-grid` | Zellen-Inhalte |

## Child-Widgets (häufig verschachtelt)

Alle im Bundle registrierten Widgets können als **`widget`-Wert** erscheinen, z. B.:


| `widget`-Wert | Vue-Komponente (nur Root) |
|---------------|---------------------------|
| `arc-widget-layout` | `ArcWidgetLayout` |
| `arc-widget-button` | `ArcWidgetButton` |


## Wann welches Format?


| Situation | Format |
|-----------|--------|
| Root-Widget in der App | `<ArcWidgetXxx :data @action />` |
| Inhalt in einem Slot | `{ widget, uid, data }` |
| Plain Text in Block | String (`value: "Text"`) |


## Fehler vermeiden

- ❌ `widget: "arcCustomLayout"` oder `widget: "ArcWidgetLayout"` — falsche ID (CamelCase)
- ❌ `uniqueId` oder `uid` **innerhalb** von `data` setzen — immer top-level (auf gleicher Ebene wie `widget` und `data`)


## Siehe auch

- [Custom Layout](/docs/widgets/custom-layout) — Layout-Blocks und `value`-Slots
- [Button](/docs/mini-widgets/buttons) — `prefix` / `suffix` als nested widgets
<!-- /host -->


---

# React-State und Events

Source: https://www.arc-rider.com/docs/patterns/react-state-events


# React-State und Events

Widgets erhalten ihre Konfiguration über `data`. Auswahl, Formulardaten, Berechtigungen und gespeicherte Datensätze verwaltest du in React oder in deinem Store.

## Ein kontrollierter Datenfluss

1. Leite das `data`-Objekt aus deinem aktuellen State ab.
2. Nimm die Eingabe über den konkreten Callback entgegen.
3. Validiere sie und speichere bei Bedarf über deine API.
4. Ersetze die betroffenen Objekte und Arrays im State.

Ändere keine übergebenen Objekte direkt. UI-Indizes sind keine Datensatz-IDs: Löse sie über die aktuelle Liste auf, bevor du Daten speicherst.

## Callback-Namen und Fallback

Die jeweilige Referenz beschreibt Argumente und Aktivierungsflags. Table benötigt etwa `clickable: true` für Zellenklicks; Steps benötigt es pro Schritt.

`onAction(type, ...args)` erhält den internen Ereignisnamen und seine Argumente. Ein konkreter Callback, etwa `onCellClick`, hat Vorrang. Für dasselbe Event laufen nicht zusätzlich beide Handler. `onAction` ist kein Action-Objekt und kein automatischer API-Aufruf.

## Asynchrones Speichern

Button wartet bei aktivierter Ladeanzeige auf das von `onClick` zurückgegebene Promise. Kanban hält den Drop-Vorgang über `onItemDrop` offen; bei Ablehnung setzt der Adapter die optimistische Verschiebung zurück. Diese Zusagen sind widgetspezifisch und gelten nicht automatisch für jeden Callback.

Fange Fehler dort ab, wo du eine Meldung für Nutzer erzeugen kannst. Beim Kanban reiche den Fehler anschließend weiter, damit der Adapter die Verschiebung abbricht.

## Datenzugriff

Widgets speichern nie selbst. Halte die Persistenz in deinem eigenen Store oder deiner API; Zugriffskontrolle, Laden und Konflikte behandelt deine Anwendung.

Referenzen: [Table](/docs/react/widgets/custom-table) und [Kanban](/docs/react/widgets/custom-kanban).


---

# Custom Drawing Teil 1: Zeichnen im Bild

Source: https://www.arc-rider.com/docs/examples/custom-drawing-zeichnen-im-bild-teil1


<!-- host:react -->
# Ein Bild annotieren und exportieren in React

Ein Bild auswählen, als Form laden, weitere Formen bearbeiten und das Ergebnis als PNG bereitstellen.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Upload liefert eine Data-URL. Drawing erhält alle Formen aus React-State. Für `onExport` verwendet der Kern aktuell `target: "field"`; der Callback liefert das Bild an React und schreibt kein Datenbankfeld.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Drawing Teil 1: Zeichnen im Bild

# Zeichnen im Bild

Im folgenden Use Case zeigen wir dir eine Schritt für Schritt Anleitung, wie du ein Tool bauen kannst, in dem du Bilder uploaden, in den Bildern zeichnen und diese wieder abspeichern kannst. Und das alles kinderleicht in Ninox.

![](https://framerusercontent.com/images/DQJphFhuKti9jLET8I1YrIHQ56U.png)

## Notwendige Widgets

- Custom Drawing
- Custom Upload
- Custom Layout
- Custom Grid
- Icon
- Button
- Image

## Vorgehensweise

Um Custom Drawing für den Use Case "Zeichnen im Bild" bei dir richtig einzusetzen, musst du einige Schritte in deiner Ninox Datenbank beachten.

<li data-preset-tag="h3">### Anlegen von Tabellen

</li>
![](https://framerusercontent.com/images/FXs6EGkJav8ct28r4gXntUaYOk.png)

- Projekte </p><ul><li data-preset-tag="p">Mängel (Untertabelle)

<ul><li data-preset-tag="p">Dokumente  (Untertabelle)

<ul><li data-preset-tag="p"><p>Shapes  (Untertabelle)

</li></ul></li></ul></li></ul><li data-preset-tag="h3">### Felder in Shapes anlegen

</li>
![](https://framerusercontent.com/images/2SOGhZq195OiG9yGhAgx6Fs3B0.png)

Folgende Felder solltest du nun in der Untertabelle Shapes anlegen. Beachte bitte, dass die Felder genauso benannt werden, wie hier aufgelistet.

#### `helper_shapeDataValue`

- Bezeichnung:  `helper_shapeDataValue`
- Typ: Text
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

#### `data_shapeData`

- Bezeichnung:  `data_shapeData`
- Typ: Funktion
- Code:


```javascript
let current := this;
let backgroundShape := first(Dokumente.Shapes[helper_shapeDataValue != null and parseJSON(helper_shapeDataValue).type = "image"]);
let parsedShapeData := parseJSON(helper_shapeDataValue);
setItem(parsedShapeData, "x", parsedShapeData.x);
setItem(parsedShapeData, "y", parsedShapeData.y);
parsedShapeData;
let isBackgroundShape := backgroundShape = Nr;
{
    dataTableId: tableId(this),
    dataFieldId: fieldId(this, "shapeDataValue"),
    sortId: if isBackgroundShape then 0 else number(Nr) end,
    isBackgroundShape: isBackgroundShape,
    movable: first(Dokumente.Shapes[helper_shapeDataValue != null and parseJSON(helper_shapeDataValue).type = "image"]) != Nr,
    x: if backgroundShape = true then
        0
    else
        number(parseJSON(helper_shapeDataValue).x)
    end,
    y: if backgroundShape = true then
        0
    else
        number(parseJSON(helper_shapeDataValue).y)
    end,
    width: parsedShapeData.width,
    height: parsedShapeData.height,
    type: parsedShapeData.type
}
```

#### `helper_disable`

- Bezeichnung:  `helper_disable`
- Typ: Ja / Nein
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

<li data-preset-tag="h3">### Felder in Dokumente anlegen

</li>
![](https://framerusercontent.com/images/onylekPc8iehfVgr8vQ1JIQLOHo.png)

#### `Dateiname`

- Bezeichnung:  `Dateiname`
- Typ: Text
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

#### `helper_base64`

- Bezeichnung:  `helper_base64`
- Typ: Text
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

#### `helper_width`

- Bezeichnung:  `helper_width`
- Typ: Zahl
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

#### `helper_height`

- Bezeichnung:  `helper_height`
- Typ: Zahl
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Server

#### `trigger_addBackgroundImage_browser`

- Bezeichnung:  `trigger_addBackgroundImage_browser`
- Typ: Text
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung:


```javascript
let current := this;
helper_base64 := trigger_addBackgroundImage_browser;
let shapeImage := text({
        type: "image",
        href: trigger_addBackgroundImage_browser,
        width: round(current.helper_width),
        height: round(current.helper_height),
        x: 0,
        y: 0
    });
if cnt(Shapes[data_shapeData.isBackgroundImage]) = 0 then
    let newShape := (create Shapes);
    newShape.(
        Dokumente := current;
        helper_shapeDataValue := shapeImage
    )
end;
'Mängel'.(helper_selectedImageDrawing := number(current.Nr));
trigger_addBackgroundImage_browser := null
```

#### `trigger_addBackgroundImage_app`

- Bezeichnung:  `trigger_addBackgroundImage_app`
- Typ: Text
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung:


```javascript
let current := this;
helper_base64 := trigger_addBackgroundImage_app;
let shapeImage := text({
        type: "image",
        href: trigger_addBackgroundImage_app,
        width: round(current.helper_width),
        height: round(current.helper_height),
        x: 0,
        y: 0
    });
if cnt(Shapes[data_shapeData.isBackgroundImage]) = 0 then
    let newShape := (create Shapes);
    newShape.(
        Dokumente := current;
        helper_shapeDataValue := shapeImage
    )
end;
trigger_addBackgroundImage_app := null;
'Mängel'.(helper_selectedImageDrawing := number(current.Nr))
```

#### `trigger_deleteImage`

- Bezeichnung:  `trigger_deleteImage`
- Typ: Ja / Nein
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung:


```javascript
let current := this;
'Mängel'.(helper_selectedImageDrawing := first(current.'Mängel'.Dokumente[Nr != current.Nr]));
delete this
```

<li data-preset-tag="h3">### Felder in Mängel anlegen

</li>
![](https://framerusercontent.com/images/0kPkYLUsef3L1wZIgaUzecnA8I.png)

Bitte erstelle dir hier einen extra Karteireiter "Helper". Das ist hilfreich, da auf dem ersten Karteireiter dein Widget Custom Drawing angezeigt wird und keine unnötigen Ninox-Felder zu sehen sein sollen. In dem Karteireiter "Helper" legst du nun folgende Felder an:

#### `helper_selectedImageDrawing`

- Bezeichnung:  `helper_selectedImageDrawing`
- Typ: Zahl
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Speicher (Browser)

#### `helper_showLayer`

- Bezeichnung:  `helper_showLayer`
- Typ: Ja / Nein
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Speicher (Browser)

#### `helper_currentColor`

- Bezeichnung:  `helper_currentColor`
- Typ: Text
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Speicher (Browser)

#### `helper_strokeWidth`

- Bezeichnung:  `helper_strokeWidth`
- Typ: Zahl
- Trigger nach Änderung: keine
- Zuweisung: Pro Datensatz im Speicher (Browser)

#### `trigger_undoLastShape`

- Bezeichnung:  `trigger_undoLastShape`
- Typ: Text
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung:


```javascript
let recordSelectedImageDrawing := record(Dokumente,number(helper_selectedImageDrawing));
if trigger_undoLastShape != null then
    let lastEdited := last(recordSelectedImageDrawing.Shapes order by 'Erstellt am');
    if trigger_undoLastShape = "undo" then
        last(recordSelectedImageDrawing.Shapes[helper_disable != true and data_shapeData.isBackgroundShape != true] order by 'Erstellt am').(helper_disable := true)
    else
        if trigger_undoLastShape = "redo" then
            lastEdited.(helper_disable := if lastEdited.helper_disable = true then
                    null
                else
                    true
                end)
        end
    end;
    trigger_undoLastShape := null
end
```

<li data-preset-tag="h3">### Widgets in Mängel einfügen

</li>
In der Tabelle Mängel fügst du nun den folgenden Anwendungscode ein. Dieser umfasst die oben beschriebenen Widgets.


```javascript
let current := this;
let fontColor := "#7a83a2";
let recordSelectedImageDrawing := record(Dokumente,helper_selectedImageDrawing);
let colors := ["#FF5733", "#33FF57", "#3357FF", "#FF33A6", "#FFC300", "#DAF7A6", "#900C3F", "#581845", "#C70039", "#FFC0CB"];
let colorSet := arcCustomGrid({
            uniqueId: "colorGrid",
            width: "100%",
            height: "auto",
            columns: "auto-fill",
            columnWidth: "38px",
            gap: "5px",
            paddingY: "20px",
            paddingX: "0",
            blocks: for item in colors do
                {
                    width: "38px",
                    height: "38px",
                    alignX: "center",
                    alignY: "center",
                    backgroundColor: item,
                    styles: html(---
border-radius: 50%; border: 4px solid { if helper_currentColor = item then }#575b79{  else }#272A40{  end };
                    ---),
                    value: "",
                    clickAction: {
                        type: "update",
                        recordId: current.Nr,
                        field: fieldId(current.Nr, "helper_currentColor"),
                        value: item
                    }
                }
            end
        });
let strokeSizes := [5, 10, 15, 20, 25, 30];
let strokeSet := arcCustomLayout({
            uniqueId: "colorGrid",
            width: "100%",
            height: "45px",
            direction: "horizontal",
            gap: "5px",
            alignX: "between",
            alignY: "center",
            paddingY: "0",
            paddingX: "0",
            blocks: for item in strokeSizes do
                {
                    width: "fraction",
                    height: "100%",
                    alignX: "center",
                    alignY: "center",
                    backgroundColor: "",
                    styles: html(---
align-items:center; justify-content:center;
 border-bottom:3px solid { if item = helper_strokeWidth then }{ if current.helper_currentColor then }{ current.helper_currentColor }{  else }#575b79{  end }{  else }#181C2B{  end }; { if item != 30 then }border-right:1px solid #262b40;{  else }{  end }
                    ---),
                    value: html(---
<div style="width:{ item }px; height:{ item }px;background-color:{ if current.helper_currentColor then }{ current.helper_currentColor }{  else }#fff{  end };border-radius:50%;"></div>
                    ---),
                    clickAction: {
                        type: "update",
                        recordId: current.Nr,
                        field: fieldId(current.Nr, "helper_strokeWidth"),
                        value: item
                    }
                }
            end
        });
let imageGrid := arcCustomGrid({
            uniqueId: "imageGrid " + Nr,
            embedded: true,
            width: "100%",
            height: "100%",
            columns: "auto-fill",
            columnWidth: "50px",
            gap: "10px",
            paddingY: "0",
            paddingX: "0",
            blocks: let images := Dokumente.[{
                        blockId: "",
                        width: "100%",
                        height: "100px",
                        alignX: "center",
                        alignY: "center",
                        paddingY: "",
                        paddingX: "",
                        backgroundColor: "",
                        lineHeight: "",
                        styles: "",
                        value: arcCustomImage({
                                uniqueId: "image mangel " + Nr,
                                title: Dateiname,
                                width: "100%",
                                height: "100%",
                                backgroundSize: "cover",
                                backgroundColor: "",
                                style: "",
                                radius: "5px",
                                borderColor: "",
                                link: helper_base64
                            }),
                        clickAction: {
                            type: "update",
                            recordId: current.Nr,
                            field: fieldId(current.Nr, "helper_selectedImageDrawing"),
                            value: number(Nr)
                        }
                    }];
            let new := [{
                        blockId: "",
                        width: "100%",
                        height: "100px",
                        alignX: "center",
                        alignY: "center",
                        paddingY: "",
                        paddingX: "",
                        backgroundColor: "#272a40",
                        lineHeight: "",
                        styles: "",
                        value: arcCustomUpload({
                                uniqueId: "multi image upload in drawing " + current.Nr,
                                capture: true,
                                multiupload: true,
                                embedded: true,
                                container: {
                                    icon: "",
                                    label: "Bilder Upload",
                                    height: "100%",
                                    width: "100%",
                                    value: arcCustomIcon({
                                            name: "plus",
                                            color: "#fff"
                                        })
                                },
                                filename: {
                                    tableId: tableId("Dokumente"),
                                    fieldId: fieldId("Dokumente", "Dateiname")
                                },
                                image: {
                                    tableId: tableId("Dokumente"),
                                    fieldId: if ninoxApp() = "web" then
                                        fieldId("Dokumente", "trigger_addBackgroundImage_browser")
                                    else
                                        fieldId("Dokumente", "trigger_addBackgroundImage_app")
                                    end,
                                    width: 2000,
                                    height: 1000,
                                    widthFieldId: fieldId("Dokumente", "helper_width"),
                                    heightFieldId: fieldId("Dokumente", "helper_height")
                                },
                                changeFieldValues: [{
                                        fieldId: fieldId("Dokumente", "Mängel"),
                                        value: number(current.Nr)
                                    }]
                            })
                    }];
            array(images, new)
        });
let drawingSticker := [{
            uid: "red_sticker",
            image: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCA3MiA3Mic+PHBhdGggZmlsbD0nI0VBNUE0NycgZD0nTTM1Ljk3MiA5LjcyYy02LjQyMiAwLTExLjY0NiA1LjIyNC0xMS42NDYgMTEuNjQ2UzI5LjU1IDMzLjAxIDM1Ljk3MiAzMy4wMWM2LjQyMSAwIDExLjY0Ni01LjIyNCAxMS42NDYtMTEuNjQ1UzQyLjM5MyA5LjcyIDM1Ljk3MiA5LjcyJy8+PHBhdGggZmlsbD0nI0QyMkYyNycgZD0nTTM5LjE2OSAzMi4zODJjMS43MjYtLjY0NiAzLjI4OS0uODE3IDQuODE0LTIuMjEyIDIuMTAyLTEuOTIzIDMuOTA0LTUuMzQgMy45MDQtOC4wMjQgMC0yLjQ0NS0uNTc4LTUuMzAzLTIuMzQyLTcuNjMzLTEuNjI4LTIuMTUtNC4zNjEtMy44NDItNi4zNzYtNC41NTQgMCAwIDMuNTE3IDUuNjUgMy41MTcgMTEuMzczcy0zLjUxNyAxMS4wNS0zLjUxNyAxMS4wNScvPjxwYXRoIGZpbGw9JyNEMENGQ0UnIGQ9J20zNS44MzcgNjMuNDg5IDIuODQ3LTcuNjdzLS44MjUtMTkuNTc3LS4zOC0xOS42NzhoLTUuMTY4Yy40NDYuMS0uMjI1IDE5LjU1OS0uMjI1IDE5LjU1OXonLz48cGF0aCBmaWxsPScjOUI5QjlBJyBkPSdtMzUuOTU2IDYyLjczOCAyLjY0OS03LjA3OHMuMTA0LTE5LjA1Ny4wNjItMTkuNTI2bC0yLjkzMy4wMDd6Jy8+PGcgZmlsbD0nbm9uZScgc3Ryb2tlPScjMDAwJyBzdHJva2UtbGluZWNhcD0ncm91bmQnIHN0cm9rZS1saW5lam9pbj0ncm91bmQnIHN0cm9rZS1taXRlcmxpbWl0PScxMCc+PGNpcmNsZSBjeD0nMzUuOTcxJyBjeT0nMjEuMzY2JyByPScxMS44MDgnIHN0cm9rZS13aWR0aD0nMicvPjxwYXRoIGQ9J00zOC41MiAzNy4wOTh2MTguNjE2bC0yLjU4NCA4LjUwNS0zLjAxNS04LjUwNVYzNy4wOTgnLz48L2c+PC9zdmc+Cg==",
            icon: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCA3MiA3Mic+PHBhdGggZmlsbD0nI0VBNUE0NycgZD0nTTM1Ljk3MiA5LjcyYy02LjQyMiAwLTExLjY0NiA1LjIyNC0xMS42NDYgMTEuNjQ2UzI5LjU1IDMzLjAxIDM1Ljk3MiAzMy4wMWM2LjQyMSAwIDExLjY0Ni01LjIyNCAxMS42NDYtMTEuNjQ1UzQyLjM5MyA5LjcyIDM1Ljk3MiA5LjcyJy8+PHBhdGggZmlsbD0nI0QyMkYyNycgZD0nTTM5LjE2OSAzMi4zODJjMS43MjYtLjY0NiAzLjI4OS0uODE3IDQuODE0LTIuMjEyIDIuMTAyLTEuOTIzIDMuOTA0LTUuMzQgMy45MDQtOC4wMjQgMC0yLjQ0NS0uNTc4LTUuMzAzLTIuMzQyLTcuNjMzLTEuNjI4LTIuMTUtNC4zNjEtMy44NDItNi4zNzYtNC41NTQgMCAwIDMuNTE3IDUuNjUgMy41MTcgMTEuMzczcy0zLjUxNyAxMS4wNS0zLjUxNyAxMS4wNScvPjxwYXRoIGZpbGw9JyNEMENGQ0UnIGQ9J20zNS44MzcgNjMuNDg5IDIuODQ3LTcuNjdzLS44MjUtMTkuNTc3LS4zOC0xOS42NzhoLTUuMTY4Yy40NDYuMS0uMjI1IDE5LjU1OS0uMjI1IDE5LjU1OXonLz48cGF0aCBmaWxsPScjOUI5QjlBJyBkPSdtMzUuOTU2IDYyLjczOCAyLjY0OS03LjA3OHMuMTA0LTE5LjA1Ny4wNjItMTkuNTI2bC0yLjkzMy4wMDd6Jy8+PGcgZmlsbD0nbm9uZScgc3Ryb2tlPScjMDAwJyBzdHJva2UtbGluZWNhcD0ncm91bmQnIHN0cm9rZS1saW5lam9pbj0ncm91bmQnIHN0cm9rZS1taXRlcmxpbWl0PScxMCc+PGNpcmNsZSBjeD0nMzUuOTcxJyBjeT0nMjEuMzY2JyByPScxMS44MDgnIHN0cm9rZS13aWR0aD0nMicvPjxwYXRoIGQ9J00zOC41MiAzNy4wOTh2MTguNjE2bC0yLjU4NCA4LjUwNS0zLjAxNS04LjUwNVYzNy4wOTgnLz48L2c+PC9zdmc+Cg==",
            label: "Red Sticker",
            width: 100,
            height: 100,
            originX: 0.5,
            originY: 0.89,
            default: true
        }, {
            uid: "green_sticker",
            image: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCA3MiA3Mic+PHBhdGggZmlsbD0nIzQ2ZWI1ZCcgZD0nTTM1Ljk3MiA5LjcyYy02LjQyMiAwLTExLjY0NiA1LjIyNC0xMS42NDYgMTEuNjQ2UzI5LjU1IDMzLjAxIDM1Ljk3MiAzMy4wMWM2LjQyMSAwIDExLjY0Ni01LjIyNCAxMS42NDYtMTEuNjQ1UzQyLjM5MyA5LjcyIDM1Ljk3MiA5LjcyJy8+PHBhdGggZmlsbD0nIzI3ZDIzZScgZD0nTTM5LjE2OSAzMi4zODJjMS43MjYtLjY0NiAzLjI4OS0uODE3IDQuODE0LTIuMjEyIDIuMTAyLTEuOTIzIDMuOTA0LTUuMzQgMy45MDQtOC4wMjQgMC0yLjQ0NS0uNTc4LTUuMzAzLTIuMzQyLTcuNjMzLTEuNjI4LTIuMTUtNC4zNjEtMy44NDItNi4zNzYtNC41NTQgMCAwIDMuNTE3IDUuNjUgMy41MTcgMTEuMzczcy0zLjUxNyAxMS4wNS0zLjUxNyAxMS4wNScvPjxwYXRoIGZpbGw9JyNEMENGQ0UnIGQ9J20zNS44MzcgNjMuNDg5IDIuODQ3LTcuNjdzLS44MjUtMTkuNTc3LS4zOC0xOS42NzhoLTUuMTY4Yy40NDYuMS0uMjI1IDE5LjU1OS0uMjI1IDE5LjU1OXonLz48cGF0aCBmaWxsPScjOUI5QjlBJyBkPSdtMzUuOTU2IDYyLjczOCAyLjY0OS03LjA3OHMuMTA0LTE5LjA1Ny4wNjItMTkuNTI2bC0yLjkzMy4wMDd6Jy8+PGcgZmlsbD0nbm9uZScgc3Ryb2tlPScjMDAwJyBzdHJva2UtbGluZWNhcD0ncm91bmQnIHN0cm9rZS1saW5lam9pbj0ncm91bmQnIHN0cm9rZS1taXRlcmxpbWl0PScxMCc+PGNpcmNsZSBjeD0nMzUuOTcxJyBjeT0nMjEuMzY2JyByPScxMS44MDgnIHN0cm9rZS13aWR0aD0nMicvPjxwYXRoIGQ9J00zOC41MiAzNy4wOTh2MTguNjE2bC0yLjU4NCA4LjUwNS0zLjAxNS04LjUwNVYzNy4wOTgnLz48L2c+PC9zdmc+Cg==",
            icon: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCA3MiA3Mic+PHBhdGggZmlsbD0nIzQ2ZWI1ZCcgZD0nTTM1Ljk3MiA5LjcyYy02LjQyMiAwLTExLjY0NiA1LjIyNC0xMS42NDYgMTEuNjQ2UzI5LjU1IDMzLjAxIDM1Ljk3MiAzMy4wMWM2LjQyMSAwIDExLjY0Ni01LjIyNCAxMS42NDYtMTEuNjQ1UzQyLjM5MyA5LjcyIDM1Ljk3MiA5LjcyJy8+PHBhdGggZmlsbD0nIzI3ZDIzZScgZD0nTTM5LjE2OSAzMi4zODJjMS43MjYtLjY0NiAzLjI4OS0uODE3IDQuODE0LTIuMjEyIDIuMTAyLTEuOTIzIDMuOTA0LTUuMzQgMy45MDQtOC4wMjQgMC0yLjQ0NS0uNTc4LTUuMzAzLTIuMzQyLTcuNjMzLTEuNjI4LTIuMTUtNC4zNjEtMy44NDItNi4zNzYtNC41NTQgMCAwIDMuNTE3IDUuNjUgMy41MTcgMTEuMzczcy0zLjUxNyAxMS4wNS0zLjUxNyAxMS4wNScvPjxwYXRoIGZpbGw9JyNEMENGQ0UnIGQ9J20zNS44MzcgNjMuNDg5IDIuODQ3LTcuNjdzLS44MjUtMTkuNTc3LS4zOC0xOS42NzhoLTUuMTY4Yy40NDYuMS0uMjI1IDE5LjU1OS0uMjI1IDE5LjU1OXonLz48cGF0aCBmaWxsPScjOUI5QjlBJyBkPSdtMzUuOTU2IDYyLjczOCAyLjY0OS03LjA3OHMuMTA0LTE5LjA1Ny4wNjItMTkuNTI2bC0yLjkzMy4wMDd6Jy8+PGcgZmlsbD0nbm9uZScgc3Ryb2tlPScjMDAwJyBzdHJva2UtbGluZWNhcD0ncm91bmQnIHN0cm9rZS1saW5lam9pbj0ncm91bmQnIHN0cm9rZS1taXRlcmxpbWl0PScxMCc+PGNpcmNsZSBjeD0nMzUuOTcxJyBjeT0nMjEuMzY2JyByPScxMS44MDgnIHN0cm9rZS13aWR0aD0nMicvPjxwYXRoIGQ9J00zOC41MiAzNy4wOTh2MTguNjE2bC0yLjU4NCA4LjUwNS0zLjAxNS04LjUwNVYzNy4wOTgnLz48L2c+PC9zdmc+Cg==",
            label: "Green Sticker",
            width: 100,
            height: 100,
            originX: 0.5,
            originY: 0.89
        }, {
            uid: "red_arrow_up_right",
            image: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2Y1MTQxNCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0yMDAsNjRWMTY4YTgsOCwwLDAsMS0xNiwwVjgzLjMxTDY5LjY2LDE5Ny42NmE4LDgsMCwwLDEtMTEuMzItMTEuMzJMMTcyLjY5LDcySDg4YTgsOCwwLDAsMSwwLTE2SDE5MkE4LDgsMCwwLDEsMjAwLDY0WiI+PC9wYXRoPjwvc3ZnPg==",
            icon: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2Y1MTQxNCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0yMDAsNjRWMTY4YTgsOCwwLDAsMS0xNiwwVjgzLjMxTDY5LjY2LDE5Ny42NmE4LDgsMCwwLDEtMTEuMzItMTEuMzJMMTcyLjY5LDcySDg4YTgsOCwwLDAsMSwwLTE2SDE5MkE4LDgsMCwwLDEsMjAwLDY0WiI+PC9wYXRoPjwvc3ZnPg==",
            label: "Pfeil 1",
            width: 100,
            height: 100,
            originX: 0.5,
            originY: 0.5,
            default: true
        }, {
            uid: "red_arrow_down_left",
            image: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2Y1MTQxNCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xOTcuNjYsNjkuNjYsODMuMzEsMTg0SDE2OGE4LDgsMCwwLDEsMCwxNkg2NGE4LDgsMCwwLDEtOC04Vjg4YTgsOCwwLDAsMSwxNiwwdjg0LjY5TDE4Ni4zNCw1OC4zNGE4LDgsMCwwLDEsMTEuMzIsMTEuMzJaIj48L3BhdGg+PC9zdmc+",
            icon: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2Y1MTQxNCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xOTcuNjYsNjkuNjYsODMuMzEsMTg0SDE2OGE4LDgsMCwwLDEsMCwxNkg2NGE4LDgsMCwwLDEtOC04Vjg4YTgsOCwwLDAsMSwxNiwwdjg0LjY5TDE4Ni4zNCw1OC4zNGE4LDgsMCwwLDEsMTEuMzIsMTEuMzJaIj48L3BhdGg+PC9zdmc+",
            label: "Pfeil 2",
            width: 100,
            height: 100,
            originX: 0,
            originY: -0.0001
        }];
let drawingArea := arcCustomDrawing({
            uniqueId: "issue board" + Nr,
            embedded: true,
            height: "100%",
            tableId: tableId("Shapes"),
            fieldId: fieldId("Shapes", "helper_shapeDataValue"),
            changeFieldValues: [{
                    fieldId: fieldId("Shapes", "Dokumente"),
                    value: helper_selectedImageDrawing
                }],
            exportSettings: {
                allowedTypes: ["jpg"],
                target: "field",
                recordId: recordSelectedImageDrawing.Nr,
                fieldId: fieldId(recordSelectedImageDrawing.Nr, "helper_base64")
            },
            canvas: {
                width: recordSelectedImageDrawing.helper_width,
                height: recordSelectedImageDrawing.helper_height,
                offsetX: 0,
                offsetY: 0
            },
            zooming: {
                step: 0.25,
                min: 0.3,
                max: 4
            },
            drawingSettings: {
                strokeWidth: if helper_strokeWidth then helper_strokeWidth else 5 end,
                strokeColor: if helper_currentColor then helper_currentColor else "#e9595c" end
            },
            artboard: {
                width: recordSelectedImageDrawing.helper_width,
                height: recordSelectedImageDrawing.helper_height
            },
            stickerTypes: drawingSticker,
            shapes: (recordSelectedImageDrawing.Shapes[helper_disable != true] order by data_shapeData.sortId).[{
                    shapeId: Nr,
                    movable: data_shapeData.movable,
                    shapeDataValue: helper_shapeDataValue,
                    sidebarItem: {
                        header: "Object ID:" + Nr,
                        content: arcCustomButton({
                                title: "Öffnen",
                                actions: [{
                                        type: "popup",
                                        recordId: Nr
                                    }]
                            })
                    }
                }],
            rightSideContent: {
                show: true,
                header: arcCustomLayout({
                        uniqueId: "drawing right side header " + Nr,
                        embedded: true,
                        direction: "vertical",
                        alignX: "left",
                        alignY: "top",
                        width: "100%",
                        height: "100%",
                        gap: "10px",
                        backgroundColor: "",
                        paddingY: "20px",
                        paddingX: "20px",
                        styles: "",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: [{
                                width: "",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                value: imageGrid
                            }]
                    }),
                content: {
                    showShapeLayers: helper_showLayer,
                    value: ""
                },
                footer: arcCustomLayout({
                        uniqueId: "drawing right side footer " + Nr,
                        embedded: true,
                        direction: "vertical",
                        alignX: "left",
                        alignY: "center",
                        width: "100%",
                        height: "",
                        gap: "0",
                        backgroundColor: "",
                        paddingY: "0",
                        paddingX: "0",
                        styles: "",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: [{
                                width: "100%",
                                height: "fraction",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "border-bottom: 1px solid #262b40;",
                                value: ""
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "border-bottom: 1px solid #262b40;",
                                value: strokeSet
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "border-bottom: 1px solid #262b40;padding:8px;",
                                value: colorSet
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "padding:8px",
                                value: arcCustomButton({
                                        uniqueId: "undo action" + Nr,
                                        title: "Aktion rückgängig",
                                        width: "100%",
                                        height: "",
                                        alignY: "",
                                        alignX: "30px",
                                        gap: "5px",
                                        fontSize: "16px",
                                        fontColor: "#fff",
                                        backgroundColor: "#272A40",
                                        borderColor: "transparent",
                                        borderRadius: "5px",
                                        showBadge: false,
                                        badgeTitle: "",
                                        badgeColor: "",
                                        badgeBackground: "",
                                        badgeBorderColor: "",
                                        badgePosition: "",
                                        actions: let id := this;
                                        [{
                                                type: "update",
                                                recordId: current.Nr,
                                                field: fieldId(current.Nr, "trigger_undoLastShape"),
                                                value: "undo"
                                            }]
                                    })
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "padding:8px",
                                value: arcCustomButton({
                                        uniqueId: "undo action" + Nr,
                                        title: "Löschen",
                                        width: "100%",
                                        height: "",
                                        alignY: "",
                                        alignX: "30px",
                                        gap: "5px",
                                        fontSize: "16px",
                                        fontColor: "#fff",
                                        backgroundColor: "#e9595c",
                                        borderColor: "transparent",
                                        borderRadius: "5px",
                                        showBadge: false,
                                        badgeTitle: "",
                                        badgeColor: "",
                                        badgeBackground: "",
                                        badgeBorderColor: "",
                                        badgePosition: "",
                                        actions: let id := this;
                                        [{
                                                type: "update",
                                                recordId: recordSelectedImageDrawing.Nr,
                                                field: fieldId(recordSelectedImageDrawing.Nr, "trigger_deleteImage"),
                                                value: true
                                            }]
                                    })
                            }]
                    })
            }
        });
arcCustomLayout({
        uniqueId: "drawing " + Nr,
        embedded: false,
        fullscreen: true,
        ninoxVersion: "3.13",
        page: false,
        fullscreenMode: if isAdminMode() then " else "full" end,
        showAdminTools: false,
        hideHeaderIcons: false,
        direction: "vertical",
        alignX: "left",
        alignY: "center",
        width: "100%",
        height: "100%",
        gap: "0",
        backgroundColor: "#181d2c",
        paddingY: "",
        paddingX: "",
        styles: "",
        scrollSettings: {
            scrollY: true
        },
        blocks: [if false then
                {
                    width: "",
                    height: "100px",
                    lineHeight: "",
                    alignX: "left",
                    paddingX: "",
                    styles: "",
                    value: arcCustomLayout({
                            uniqueId: "layout header " + Nr,
                            embedded: true,
                            direction: "horizontal",
                            alignX: "left",
                            alignY: "center",
                            width: "100%",
                            height: "100%",
                            gap: "10px",
                            backgroundColor: "",
                            paddingY: "",
                            paddingX: "",
                            styles: "border-bottom: 1px solid #262b40;",
                            scrollSettings: {
                                scrollY: true
                            },
                            blocks: [{
                                    width: "fraction",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "left",
                                    color: "",
                                    styles: "font-size:24px;color:#7a83a2;text-wrap:nowrap;padding:0 40px;",
                                    value: html(---
 Title
                                    ---)
                                }, {
                                    width: "auto",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "right",
                                    color: "",
                                    value: arcCustomButton({
                                            uniqueId: "Button schließen" + Nr,
                                            title: "Schließen",
                                            width: "",
                                            height: "",
                                            alignY: "",
                                            alignX: "",
                                            paddingX: "",
                                            paddingY: "",
                                            gap: "5px",
                                            icon: arcCustomIcon({
                                                    name: "x",
                                                    color: fontColor
                                                }),
                                            iconPosition: "right",
                                            fontSize: "",
                                            fontColor: fontColor,
                                            backgroundColor: "transparent",
                                            borderColor: "transparent",
                                            borderRadius: "5px",
                                            actions: [{
                                                    type: "openRecord",
                                                    tab: "Allgemeines",
                                                    recordId: current.Nr
                                                }]
                                        })
                                }]
                        })
                }
            end, if false then
                {
                    width: "100%",
                    height: "50px",
                    lineHeight: "",
                    alignX: "left",
                    color: "",
                    backgroundColor: "#141925",
                    styles: "border-bottom: 1px solid #262b40;border-top: 1px solid #262b40;",
                    value: arcCustomLayout({
                            uniqueId: "layout action bar " + Nr,
                            embedded: true,
                            fullscreen: false,
                            ninoxVersion: "",
                            page: true,
                            fullscreenMode: "",
                            showAdminTools: true,
                            hideHeaderIcons: true,
                            direction: "horizontal",
                            alignX: "left",
                            alignY: "center",
                            width: "",
                            height: "",
                            gap: "10px",
                            backgroundColor: "",
                            paddingY: "",
                            paddingX: "",
                            styles: "",
                            scrollSettings: {
                                scrollY: false,
                                scrollX: false
                            },
                            blocks: [{
                                    width: "200px",
                                    height: "100%",
                                    lineHeight: "",
                                    alignX: "left",
                                    color: "",
                                    styles: "",
                                    value: "block 1"
                                }, {
                                    width: "",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "left",
                                    color: "",
                                    value: "block 2"
                                }]
                        })
                }
            end, {
                width: "100%",
                height: "100%",
                lineHeight: "",
                alignX: "left",
                color: "",
                backgroundColor: "#181d2c",
                value: drawingArea
            }]
    })
```

**Tadaaaaa 🧙🏼‍♀️ Das Widget Zeichnen im Bild sollte nun funktionsfähig bei dir laufen. **
<!-- /host -->


---

# Custom Drawing Teil 2: Mangel-Verortung mit Pins

Source: https://www.arc-rider.com/docs/examples/custom-drawing-teil-2-mangel-verortung-mit-pins


<!-- host:react -->
# Markierungen auf einem Plan in React

Markierungen auswählen und ihre Positionen lokal speichern und erneut laden.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Die Form-ID verbindet eine Markierung mit deinem Datensatz. In einer Produktivanwendung speicherst du die Formen über deine API und validierst geladene Daten.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Drawing Teil 2: Mangel-Verortung mit Pins

# Mangel-Verortung mit Pins

![](https://framerusercontent.com/images/XSN9KLdAVIgeizkqag1BjBvXo.png)

In [Custom Drawing Teil 1: Zeichnen im Bild](https://www.arc-rider.de/documentation/custom-drawing) hast du gelernt, wie du ein Tool entwickelst, mit dem du Bilder hochladen, darin zeichnen und die bearbeiteten Bilder wieder abspeichern kannst.

In diesem **Teil 2** zeigen wir dir, wie du **PDF-Dateien hochladen** und darauf **Pins setzen** kannst – zum Beispiel für die **Mangelverortung**. Das User Interface unterscheidet sich hier insbesondere im rechten Aktionsbereich, wo die Mängel direkt klickbar sind.

Zusätzlich können **Pläne versioniert** werden, etwa wenn Änderungen am Plan vorgenommen werden. Das Besondere dabei: **Beim Duplizieren bleiben die Mängel erhalten**, während sich der zugrunde liegende Plan aktualisieren kann. So lassen sich Änderungen effizient nachvollziehen und verwalten.

## Notwendige Widgets

- Custom Drawing
- Custom Upload
- Custom Layout
- Input
- Icon
- Button
- Image

## Vorgehensweise

Um Custom Drawing für den Use Case "Pin-Verortung auf PDF" bei dir richtig einzusetzen, musst du einige Schritte in deiner Ninox Datenbank beachten.

<li data-preset-tag="h3">### Anlegen von Tabellen

</li>
In [Custom Drawing Teil 1: Zeichnen im Bild](https://www.arc-rider.de/documentation/custom-drawing) hast du folgende Tabellen bereits angelegt:

- Projekte </p><ul><li data-preset-tag="p">Mängel (Untertabelle)

<ul><li data-preset-tag="p">Dokumente  (Untertabelle)

<ul><li data-preset-tag="p"><p>Shapes  (Untertabelle)

</li></ul></li></ul></li></ul>**Was neu dazu kommt: **Für die Pin-Verortung legst du nun eine neue Tabelle "Pläne" an. Diese wird mit Projekte verknüpft. Außerdem ist es wichtig, dass Shapes direkt mit Mängel (N:1) verknüpft wird und nicht nur, wie bislang, mit Dokumente.

- Projekte </p><ul><li data-preset-tag="p"><p>Pläne (Untertabelle)
- Mängel (Untertabelle) </p><ul><li data-preset-tag="p">Dokumente  (Untertabelle)

<ul><li data-preset-tag="p"><p>Shapes  (Untertabelle)

</li></ul></li></ul></li></ul><li data-preset-tag="h3">### Felder in Shapes anlegen

</li>
In [Custom Drawing Teil 1: Zeichnen im Bild](https://www.arc-rider.de/documentation/custom-drawing) hast du die Grundlage aller Felder geschaffen. Folgend werden nur Änderungen oder Ergänzungen erläutert.

Bitte verknüpfe in der Tabelle Shapes die Tabelle Mängel. (N:1)

#### `Mängel`

- Bezeichnung:  `Mängel`
- Typ: Verknüpfung
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

![](https://framerusercontent.com/images/Ds2ai9f0JnAY41kcEDmjNMKUaf4.png)

#### `trigger_createMangel`

- Bezeichnung:  `trigger_createMangel`
- Typ: Text
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung:


```javascript
let current := this;
let newMangel := (create 'Mängel');
newMangel.(Projekte := current.Dokumente.'Pläne'.Projekte);
'Mängel' := newMangel
```

<li data-preset-tag="h3">### Felder in Dokumente anlegen

</li>
In [Custom Drawing Teil 1: Zeichnen im Bild](https://www.arc-rider.de/documentation/custom-drawing) hast du die Grundlage aller Felder geschaffen. Folgend werden nur Änderungen oder Ergänzungen erläutert.

#### `Pläne`

- Bezeichnung:  `Pläne`
- Typ: Verknüpfung
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

![](https://framerusercontent.com/images/vArz7BA7MbQNGAaCuZamFTp4DY.png)

#### `trigger_addBackgroundImage_browser`

- Bezeichnung:  `trigger_addBackgroundImage_browser`
- Typ: Text
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: **(Neu)**


```javascript
let current := this;
let recordDuplicatePlan := record(Dokumente,number('Pläne'.helper_duplicateVersion));
helper_base64 := trigger_addBackgroundImage_browser;
let shapeImage := text({
        type: "image",
        href: trigger_addBackgroundImage_browser,
        width: round(current.helper_width),
        height: round(current.helper_height),
        x: 0,
        y: 0
    });
if cnt(Shapes[data_shapeData.isBackgroundImage]) = 0 then
    let newShape := (create Shapes);
    newShape.(
        Dokumente := current;
        helper_shapeDataValue := shapeImage
    )
end;
if recordDuplicatePlan then
    let duplicatedShapes := recordDuplicatePlan.Shapes;
    for item in duplicatedShapes[data_shapeData.isBackgroundShape != true] do
        let newShape := (create Shapes);
        newShape.(
            Dokumente := current.Nr;
            helper_shapeDataValue := item.helper_shapeDataValue;
            'Mängel' := item.'Mängel'
        )
    end
end;
'Pläne'.(helper_duplicateVersion := null);
'Pläne'.(helper_selectedImageDrawing := number(current.Nr));
trigger_addBackgroundImage_browser := null
```

#### `trigger_addBackgroundImage_app`

- Bezeichnung:  `trigger_addBackgroundImage_app`
- Typ: Text
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung: **(Neu)**


```javascript
let current := this;
helper_base64 := trigger_addBackgroundImage_app;
let shapeImage := text({
        type: "image",
        href: trigger_addBackgroundImage_app,
        width: round(current.helper_width),
        height: round(current.helper_height),
        x: 0,
        y: 0
    });
if cnt(Shapes[data_shapeData.isBackgroundImage]) = 0 then
    let newShape := (create Shapes);
    newShape.(
        Dokumente := current;
        helper_shapeDataValue := shapeImage
    )
end;
let recordDuplicatePlan := record(Dokumente,number('Pläne'.helper_duplicateVersion));
if recordDuplicatePlan then
    let duplicatedShapes := recordDuplicatePlan.Shapes;
    for item in duplicatedShapes[data_shapeData.isBackgroundShape != true] do
        let newShape := (create Shapes);
        newShape.(
            Dokumente := current.Nr;
            helper_shapeDataValue := item.helper_shapeDataValue;
            'Mängel' := item.'Mängel'
        )
    end
end;
'Pläne'.(helper_duplicateVersion := null);
'Pläne'.(helper_selectedImageDrawing := number(current.Nr));
trigger_addBackgroundImage_app := null
```

#### `trigger_deleteImage`

- Bezeichnung:  `trigger_deleteImage`
- Typ: Ja / Nein
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung: **(Neu)**


```javascript
let current := this;
if dialog("Plan-Version löschen", "Soll diese Plan-Version wirklich gelöscht werden?", ["Ja, löschen!", "Abbrechen"]) = "Ja, löschen!" then
    'Pläne'.(helper_selectedImageDrawing := number(first(current.'Pläne'.Dokumente[Nr != current.Nr]).Nr));
    delete this
end;
trigger_deleteImage := null
```

<li data-preset-tag="h3">### Felder in `Pläne` anlegen

</li>
In der Tabelle legst du dir einen Karteireiter "Helper" an, damit alle Hilfsfelder hier erstellt werden und auf dem ersten Karteireiter dein Custom Drawing Image liegen kann.

![](https://framerusercontent.com/images/ZXqJg1Ln3GN9ietnyxtz1diUxg.png)

#### `Bezeichnung`

- Bezeichnung:  `Bezeichnung`
- Typ: Text
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

#### `helper_base64`

- Bezeichnung:  `helper_base64`
- Typ: Text
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

#### `helper_selectedImageDrawing`

- Bezeichnung:  `helper_selectedImageDrawing`
- Typ: Zahl
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

#### `helper_duplicateVersion`

- Bezeichnung:  `helper_duplicateVersion`
- Typ: Text
- Zuweisung: Pro Datensatz im Server
- Trigger nach Änderung: Keine

#### `trigger_cancelUpload`

- Bezeichnung:  `trigger_cancelUpload`
- Typ: Text
- Zuweisung: Pro Datensatz im Speicher (Browser)
- Trigger nach Änderung:


```javascript
if cnt(Dokumente) = 0 then
    if dialog("Abbrechen", "Soll der gesamte Plan wirklich gelöscht werden?", ["Ja, löschen!", "Abbrechen"]) = "Ja, löschen!" then
        delete this
    end
else
    if helper_duplicateVersion != null then
        if dialog("Duplizieren abbrechen?", "Soll der Vorgang wirklich abgebrochen werden?", ["Ja", "Nein"]) = "Ja" then
            helper_duplicateVersion := null
        end
    end;
    trigger_cancelUpload := null
end
```

<li data-preset-tag="h3">### Widgets in Pläne einfügen

</li>
In der Tabelle Pläne fügst du nun den folgenden Anwendungscode ein. Dieser umfasst die oben beschriebenen Widgets.


```javascript
let current := this;
let fontColor := "#7a83a2";
let recordSelectedImageDrawing := record(Dokumente,helper_selectedImageDrawing);
let drawingSticker := [{
            uid: "red_sticker",
            image: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0icGluIiBkYXRhLW5hbWU9InBpbiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNTYwIDgwMCI+CiAgPGcgaWQ9InBpbiI+CiAgICA8cGF0aCBpZD0icGluLTIiIGRhdGEtbmFtZT0icGluIiAgZmlsbD0iIzNlNmZmZiIgZD0iTTU2MCwyODBjMCwxNTQuNjUtMjgwLDUyMC0yODAsNTIwLDAsMC0yODAtMzY1LjM1LTI4MC01MjBTMTI1LjM2LDAsMjgwLDBzMjgwLDEyNS4zNSwyODAsMjgwIi8+CiAgICA8cGF0aCBpZD0icm91bmRfb3V0ZXIiIGRhdGEtbmFtZT0icm91bmQgb3V0ZXIiIGZpbGw9IiNmZmYiIGQ9Ik00NTguMiwzMDUuMzljMC05OC40MS03OS43Ny0xNzguMi0xNzguMi0xNzguMnMtMTc4LjIsNzkuNzktMTc4LjIsMTc4LjIsNzkuNzcsMTc4LjIsMTc4LjIsMTc4LjIsMTc4LjItNzkuNzYsMTc4LjItMTc4LjIiLz4KICAgIDxwYXRoIGlkPSJyb3VuZF9pbm5lciIgZGF0YS1uYW1lPSJyb3VuZCBpbm5lciIgZmlsbD0iI2U5NTk1YyIgZD0iTTQwMS45NiwzMDUuMzljMCw2Ny4yNC01NC43NiwxMjEuOTYtMTIxLjk2LDEyMS45NnMtMTIxLjk2LTU0LjczLTEyMS45Ni0xMjEuOTYsNTQuNzYtMTIxLjk2LDEyMS45Ni0xMjEuOTYsMTIxLjk2LDU0Ljc5LDEyMS45NiwxMjEuOTYiLz4KICA8L2c+Cjwvc3ZnPg==",
            icon: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0icGluIiBkYXRhLW5hbWU9InBpbiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNTYwIDgwMCI+CiAgPGcgaWQ9InBpbiI+CiAgICA8cGF0aCBpZD0icGluLTIiIGRhdGEtbmFtZT0icGluIiAgZmlsbD0iIzNlNmZmZiIgZD0iTTU2MCwyODBjMCwxNTQuNjUtMjgwLDUyMC0yODAsNTIwLDAsMC0yODAtMzY1LjM1LTI4MC01MjBTMTI1LjM2LDAsMjgwLDBzMjgwLDEyNS4zNSwyODAsMjgwIi8+CiAgICA8cGF0aCBpZD0icm91bmRfb3V0ZXIiIGRhdGEtbmFtZT0icm91bmQgb3V0ZXIiIGZpbGw9IiNmZmYiIGQ9Ik00NTguMiwzMDUuMzljMC05OC40MS03OS43Ny0xNzguMi0xNzguMi0xNzguMnMtMTc4LjIsNzkuNzktMTc4LjIsMTc4LjIsNzkuNzcsMTc4LjIsMTc4LjIsMTc4LjIsMTc4LjItNzkuNzYsMTc4LjItMTc4LjIiLz4KICAgIDxwYXRoIGlkPSJyb3VuZF9pbm5lciIgZGF0YS1uYW1lPSJyb3VuZCBpbm5lciIgZmlsbD0iI2U5NTk1YyIgZD0iTTQwMS45NiwzMDUuMzljMCw2Ny4yNC01NC43NiwxMjEuOTYtMTIxLjk2LDEyMS45NnMtMTIxLjk2LTU0LjczLTEyMS45Ni0xMjEuOTYsNTQuNzYtMTIxLjk2LDEyMS45Ni0xMjEuOTYsMTIxLjk2LDU0Ljc5LDEyMS45NiwxMjEuOTYiLz4KICA8L2c+Cjwvc3ZnPg==",
            label: "Roter Pin",
            width: 60,
            height: 60,
            originX: 0.5,
            originY: 0.89,
            default: true
        }, {
            uid: "green_sticker",
            image: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0icGluIiBkYXRhLW5hbWU9InBpbiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNTYwIDgwMCI+CiAgPGcgaWQ9InBpbiI+CiAgICA8cGF0aCBpZD0icGluLTIiIGRhdGEtbmFtZT0icGluIiAgZmlsbD0iIzNlNmZmZiIgZD0iTTU2MCwyODBjMCwxNTQuNjUtMjgwLDUyMC0yODAsNTIwLDAsMC0yODAtMzY1LjM1LTI4MC01MjBTMTI1LjM2LDAsMjgwLDBzMjgwLDEyNS4zNSwyODAsMjgwIi8+CiAgICA8cGF0aCBpZD0icm91bmRfb3V0ZXIiIGRhdGEtbmFtZT0icm91bmQgb3V0ZXIiIGZpbGw9IiNmZmYiIGQ9Ik00NTguMiwzMDUuMzljMC05OC40MS03OS43Ny0xNzguMi0xNzguMi0xNzguMnMtMTc4LjIsNzkuNzktMTc4LjIsMTc4LjIsNzkuNzcsMTc4LjIsMTc4LjIsMTc4LjIsMTc4LjItNzkuNzYsMTc4LjItMTc4LjIiLz4KICAgIDxwYXRoIGlkPSJyb3VuZF9pbm5lciIgZGF0YS1uYW1lPSJyb3VuZCBpbm5lciIgZmlsbD0iIzc1YjY0OSIgZD0iTTQwMS45NiwzMDUuMzljMCw2Ny4yNC01NC43NiwxMjEuOTYtMTIxLjk2LDEyMS45NnMtMTIxLjk2LTU0LjczLTEyMS45Ni0xMjEuOTYsNTQuNzYtMTIxLjk2LDEyMS45Ni0xMjEuOTYsMTIxLjk2LDU0Ljc5LDEyMS45NiwxMjEuOTYiLz4KICA8L2c+Cjwvc3ZnPg==",
            icon: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0icGluIiBkYXRhLW5hbWU9InBpbiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNTYwIDgwMCI+CiAgPGcgaWQ9InBpbiI+CiAgICA8cGF0aCBpZD0icGluLTIiIGRhdGEtbmFtZT0icGluIiAgZmlsbD0iIzNlNmZmZiIgZD0iTTU2MCwyODBjMCwxNTQuNjUtMjgwLDUyMC0yODAsNTIwLDAsMC0yODAtMzY1LjM1LTI4MC01MjBTMTI1LjM2LDAsMjgwLDBzMjgwLDEyNS4zNSwyODAsMjgwIi8+CiAgICA8cGF0aCBpZD0icm91bmRfb3V0ZXIiIGRhdGEtbmFtZT0icm91bmQgb3V0ZXIiIGZpbGw9IiNmZmYiIGQ9Ik00NTguMiwzMDUuMzljMC05OC40MS03OS43Ny0xNzguMi0xNzguMi0xNzguMnMtMTc4LjIsNzkuNzktMTc4LjIsMTc4LjIsNzkuNzcsMTc4LjIsMTc4LjIsMTc4LjIsMTc4LjItNzkuNzYsMTc4LjItMTc4LjIiLz4KICAgIDxwYXRoIGlkPSJyb3VuZF9pbm5lciIgZGF0YS1uYW1lPSJyb3VuZCBpbm5lciIgZmlsbD0iIzc1YjY0OSIgZD0iTTQwMS45NiwzMDUuMzljMCw2Ny4yNC01NC43NiwxMjEuOTYtMTIxLjk2LDEyMS45NnMtMTIxLjk2LTU0LjczLTEyMS45Ni0xMjEuOTYsNTQuNzYtMTIxLjk2LDEyMS45Ni0xMjEuOTYsMTIxLjk2LDU0Ljc5LDEyMS45NiwxMjEuOTYiLz4KICA8L2c+Cjwvc3ZnPg==",
            label: "Green Sticker",
            width: 60,
            height: 60,
            originX: 0.5,
            originY: 0.89
        }];
let drawingArea := arcCustomDrawing({
            uniqueId: "issue board" + Nr,
            embedded: true,
            height: "100%",
            tableId: tableId("Shapes"),
            fieldId: fieldId("Shapes", "helper_shapeDataValue"),
            changeFieldValues: [{
                    fieldId: fieldId("Shapes", "Dokumente"),
                    value: helper_selectedImageDrawing
                }, {
                    fieldId: fieldId("Shapes", "trigger_createMangel"),
                    value: "create"
                }],
            exportSettings: {
                allowedTypes: ["jpg", "png", "svg", "pdf"],
                target: "file",
                recordId: recordSelectedImageDrawing.Nr,
                fieldId: fieldId(recordSelectedImageDrawing.Nr, "helper_base64")
            },
            canvas: {
                width: recordSelectedImageDrawing.helper_width,
                height: recordSelectedImageDrawing.helper_height,
                offsetX: 0,
                offsetY: 0
            },
            zooming: {
                step: 0.25,
                min: 0.3,
                max: 4
            },
            drawingSettings: {
                strokeWidth: 1,
                strokeColor: "#e9595c"
            },
            artboard: {
                width: recordSelectedImageDrawing.helper_width,
                height: recordSelectedImageDrawing.helper_height
            },
            stickerTypes: drawingSticker,
            shapes: (recordSelectedImageDrawing.Shapes[helper_disable != true] order by data_shapeData.sortId).[{
                    shapeId: Nr,
                    movable: data_shapeData.movable,
                    shapeDataValue: helper_shapeDataValue,
                    sidebarItem: {
                        header: arcCustomLayout({
                                uniqueId: "Beispiel " + Nr,
                                embedded: true,
                                fullscreen: false,
                                ninoxVersion: "",
                                page: true,
                                fullscreenMode: "",
                                showAdminTools: true,
                                hideHeaderIcons: true,
                                direction: "horizontal",
                                alignX: "left",
                                alignY: "center",
                                width: "",
                                height: "",
                                gap: "10px",
                                backgroundColor: "",
                                paddingY: "",
                                paddingX: "",
                                styles: "",
                                scrollSettings: {
                                    scrollY: false,
                                    scrollX: false
                                },
                                blocks: [{
                                        width: "fraction",
                                        height: "auto",
                                        lineHeight: "",
                                        alignX: "left",
                                        color: "#fff",
                                        styles: "",
                                        value: if data_shapeData.isBackgroundShape != true then
                                            "Mangel ID:" + 'Mängel'.Nr
                                        else
                                            "Plan Hintergrund"
                                        end
                                    }, if data_shapeData.isBackgroundShape != true then
                                        {
                                            width: "auto",
                                            height: "auto",
                                            lineHeight: "",
                                            alignX: "left",
                                            color: "",
                                            value: arcCustomButton({
                                                    title: "Öffnen",
                                                    height: "20px",
                                                    width: "auto",
                                                    actions: [{
                                                            type: "popup",
                                                            recordId: 'Mängel'.Nr
                                                        }]
                                                })
                                        }
                                    end]
                            }),
                        content: if data_shapeData.isBackgroundShape != true then
                            arcCustomButton({
                                    uniqueId: "undo action" + Nr,
                                    title: "Mangel löschen",
                                    width: "100%",
                                    height: "",
                                    alignY: "",
                                    alignX: "30px",
                                    gap: "5px",
                                    fontSize: "16px",
                                    fontColor: "#fff",
                                    backgroundColor: "#e9595c",
                                    borderColor: "transparent",
                                    borderRadius: "5px",
                                    showBadge: false,
                                    badgeTitle: "",
                                    badgeColor: "",
                                    badgeBackground: "",
                                    badgeBorderColor: "",
                                    badgePosition: "",
                                    actions: let id := this;
                                    [{
                                            type: "update",
                                            recordId: 'Mängel'.Nr,
                                            field: fieldId('Mängel'.Nr, "trigger_deleteMangel"),
                                            value: true
                                        }]
                                })
                        end
                    }
                }],
            rightSideContent: {
                show: true,
                header: arcCustomLayout({
                        uniqueId: "drawing right side header " + Nr,
                        embedded: true,
                        direction: "vertical",
                        alignX: "left",
                        alignY: "top",
                        width: "100%",
                        height: "100%",
                        gap: "10px",
                        backgroundColor: "",
                        paddingY: "20px",
                        paddingX: "20px",
                        styles: "",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: [{
                                width: "",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "#fff",
                                value: "Plan-Version ID " + helper_selectedImageDrawing
                            }]
                    }),
                content: {
                    showShapeLayers: true,
                    value: ""
                },
                footer: arcCustomLayout({
                        uniqueId: "drawing right side footer " + Nr,
                        embedded: true,
                        direction: "vertical",
                        alignX: "left",
                        alignY: "center",
                        width: "100%",
                        height: "",
                        gap: "0",
                        backgroundColor: "",
                        paddingY: "0",
                        paddingX: "0",
                        styles: "",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: [{
                                width: "100%",
                                height: "fraction",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "border-bottom: 1px solid #262b40;",
                                value: ""
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "padding:8px;padding-bottom:0;",
                                value: arcCustomButton({
                                        uniqueId: "undo action" + Nr,
                                        title: "Duplizieren",
                                        width: "100%",
                                        height: "",
                                        alignY: "",
                                        alignX: "30px",
                                        gap: "5px",
                                        fontSize: "16px",
                                        fontColor: "#fff",
                                        backgroundColor: "#272A40",
                                        borderColor: "transparent",
                                        borderRadius: "5px",
                                        showBadge: false,
                                        badgeTitle: "",
                                        badgeColor: "",
                                        badgeBackground: "",
                                        badgeBorderColor: "",
                                        badgePosition: "",
                                        actions: let id := this;
                                        [{
                                                type: "update",
                                                recordId: current.Nr,
                                                field: fieldId(current.Nr, "helper_duplicateVersion"),
                                                value: number(helper_selectedImageDrawing)
                                            }]
                                    })
                            }, {
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "padding:8px",
                                value: arcCustomButton({
                                        uniqueId: "undo action" + Nr,
                                        title: "Löschen",
                                        width: "100%",
                                        height: "",
                                        alignY: "",
                                        alignX: "30px",
                                        gap: "5px",
                                        fontSize: "16px",
                                        fontColor: "#fff",
                                        backgroundColor: "#e9595c",
                                        borderColor: "transparent",
                                        borderRadius: "5px",
                                        showBadge: false,
                                        badgeTitle: "",
                                        badgeColor: "",
                                        badgeBackground: "",
                                        badgeBorderColor: "",
                                        badgePosition: "",
                                        actions: let id := this;
                                        [{
                                                type: "update",
                                                recordId: recordSelectedImageDrawing.Nr,
                                                field: fieldId(recordSelectedImageDrawing.Nr, "trigger_deleteImage"),
                                                value: true
                                            }]
                                    })
                            }]
                    })
            }
        });
arcCustomLayout({
        uniqueId: "drawing " + Nr,
        embedded: false,
        fullscreen: true,
        ninoxVersion: "3.13",
        page: false,
        fullscreenMode: if isAdminMode() then " else "full" end,
        showAdminTools: false,
        hideHeaderIcons: false,
        direction: "vertical",
        alignX: "left",
        alignY: "top",
        width: "100%",
        height: "100%",
        gap: "0",
        backgroundColor: "#181d2c",
        paddingY: "",
        paddingX: "",
        styles: "",
        scrollSettings: {
            scrollY: true
        },
        blocks: [{
                width: "",
                height: "100px",
                lineHeight: "",
                alignX: "left",
                paddingX: "",
                styles: "",
                value: arcCustomLayout({
                        uniqueId: "layout header " + Nr,
                        embedded: true,
                        direction: "horizontal",
                        alignX: "left",
                        alignY: "center",
                        width: "100%",
                        height: "100%",
                        gap: "10px",
                        backgroundColor: "",
                        paddingY: "",
                        paddingX: "",
                        styles: "",
                        scrollSettings: {
                            scrollY: true
                        },
                        blocks: [{
                                width: "fraction",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "font-size:24px;color:#7a83a2;text-wrap:nowrap;padding:0 40px;",
                                value: arcCustomInput({
                                        uniqueId: "Plan Titel " + Nr,
                                        recordId: Nr,
                                        fieldId: fieldId("Pläne", "Bezeichnung"),
                                        title: text(Bezeichnung),
                                        value: text(Bezeichnung),
                                        type: "text",
                                        embedded: true,
                                        disabled: false,
                                        tempStorage: false,
                                        suffix: "",
                                        width: "",
                                        height: "",
                                        alignX: "left",
                                        paddingY: "",
                                        paddingX: "0",
                                        fontColor: "#7a83a2",
                                        fontSize: "24px",
                                        fontWeight: "",
                                        backgroundColor: "transparent",
                                        borderWidth: "",
                                        borderColor: "transparent",
                                        borderRadius: "",
                                        placeholderSettings: {
                                            value: "Bezeichnung des Plans",
                                            fontColor: "#7a83a288",
                                            backgroundColor: "transparent"
                                        },
                                        focusAction: {
                                            width: "100%",
                                            showFocusOutline: true,
                                            outlineWidth: "4px",
                                            outlineColor: "#04CD10"
                                        },
                                        labelSettings: {
                                            title: "",
                                            fontSize: "",
                                            alignX: "",
                                            gap: ""
                                        }
                                    })
                            }, {
                                width: "auto",
                                height: "auto",
                                lineHeight: "",
                                alignX: "right",
                                color: "",
                                value: arcCustomButton({
                                        uniqueId: "Button schließen" + Nr,
                                        title: "Schließen",
                                        width: "",
                                        height: "",
                                        alignY: "",
                                        alignX: "",
                                        paddingX: "",
                                        paddingY: "",
                                        gap: "5px",
                                        icon: arcCustomIcon({
                                                name: "x",
                                                color: fontColor
                                            }),
                                        iconPosition: "right",
                                        fontSize: "",
                                        fontColor: fontColor,
                                        backgroundColor: "transparent",
                                        borderColor: "transparent",
                                        borderRadius: "5px",
                                        actions: [{
                                                type: "closeRecord",
                                                recordId: current.Nr
                                            }]
                                    })
                            }]
                    })
            }, {
                width: "100%",
                height: "50px",
                lineHeight: "",
                alignX: "left",
                color: "",
                backgroundColor: "#141925",
                styles: "border-bottom: 1px solid #262b40;border-top: 1px solid #262b40;",
                value: arcCustomLayout({
                        comment: "Tab menu ausblenden",
                        uniqueId: "Beispiel " + Nr,
                        embedded: true,
                        fullscreen: false,
                        ninoxVersion: "",
                        page: true,
                        fullscreenMode: "",
                        showAdminTools: true,
                        hideHeaderIcons: true,
                        direction: "horizontal",
                        alignX: "left",
                        alignY: "bottom",
                        width: "100%",
                        height: "100%",
                        gap: "0",
                        backgroundColor: "",
                        paddingY: "",
                        paddingX: "",
                        styles: "",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: Dokumente.[{
                                width: "auto",
                                height: "40px",
                                lineHeight: "",
                                alignX: "left",
                                color: fontColor,
                                backgroundColor: if current.recordSelectedImageDrawing = number(Nr) then
                                    "#272A40"
                                else
                                    "#181d2c"
                                end,
                                styles: "font-weight:600; padding:0 20px; border-left: 1px solid #262b40;border-right: 1px solid #262b40;",
                                value: arcCustomLayout({
                                        uniqueId: "Beispiel " + Nr,
                                        embedded: true,
                                        direction: "horizontal",
                                        alignX: "left",
                                        alignY: "center",
                                        width: "auto",
                                        height: "",
                                        gap: "10px",
                                        backgroundColor: "",
                                        paddingY: "",
                                        paddingX: "",
                                        styles: "",
                                        scrollSettings: {
                                            scrollY: false,
                                            scrollX: false
                                        },
                                        blocks: [{
                                                width: "auto",
                                                height: "auto",
                                                lineHeight: "",
                                                alignX: "left",
                                                color: fontColor,
                                                styles: "",
                                                value: "Plan-Version Nr." + Nr
                                            }]
                                    }),
                                clickAction: {
                                    type: "update",
                                    recordId: current.Nr,
                                    field: fieldId(current.Nr, "helper_selectedImageDrawing"),
                                    value: number(Nr)
                                }
                            }]
                    })
            }, {
                width: "100%",
                height: "100%",
                lineHeight: "",
                alignX: "left",
                color: "",
                backgroundColor: "#181d2c",
                value: if helper_duplicateVersion != null or cnt(Dokumente) = 0 then
                    arcCustomLayout({
                            uniqueId: "Upload und Button " + Nr,
                            embedded: true,
                            fullscreen: false,
                            ninoxVersion: "",
                            page: true,
                            fullscreenMode: "",
                            showAdminTools: true,
                            hideHeaderIcons: true,
                            direction: "vertical",
                            alignX: "left",
                            alignY: "top",
                            width: "",
                            height: "",
                            gap: "5px",
                            backgroundColor: "",
                            paddingY: "",
                            paddingX: "",
                            styles: "",
                            scrollSettings: {
                                scrollY: false,
                                scrollX: false
                            },
                            blocks: [{
                                    comment: "------------------------------- Custom Upload ------------------------------",
                                    width: "",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "center",
                                    color: "",
                                    styles: "",
                                    value: arcCustomUpload({
                                            uniqueId: "multi image upload in drawing " + current.Nr,
                                            capture: false,
                                            multiupload: false,
                                            embedded: true,
                                            container: {
                                                icon: "",
                                                label: "Bilder Upload",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomLayout({
                                                        uniqueId: "Beispiel " + Nr,
                                                        embedded: true,
                                                        fullscreen: false,
                                                        ninoxVersion: "",
                                                        page: true,
                                                        fullscreenMode: "",
                                                        showAdminTools: true,
                                                        hideHeaderIcons: true,
                                                        direction: "vertical",
                                                        alignX: "center",
                                                        alignY: "center",
                                                        width: "",
                                                        height: "100%",
                                                        gap: "10px",
                                                        backgroundColor: "",
                                                        paddingY: "",
                                                        paddingX: "",
                                                        styles: "",
                                                        scrollSettings: {
                                                            scrollY: false,
                                                            scrollX: false
                                                        },
                                                        blocks: [{
                                                                width: "auto",
                                                                height: "auto",
                                                                lineHeight: "",
                                                                alignX: "left",
                                                                color: "",
                                                                styles: "border-radius:50px;overflow:hidden;",
                                                                value: html(---
<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" style="background-color:#7a83a2;"><path fill="#181d2c" d="M29 21v6a.75.75 0 0 1-.75.75h-16.5A.75.75 0 0 1 11 27v-6a.75.75 0 0 1 1.5 0v5.25h15V21a.75.75 0 0 1 1.5 0m-12.219-6.219 2.469-2.471V21a.75.75 0 0 0 1.5 0v-8.69l2.469 2.471a.751.751 0 0 0 1.062-1.062l-3.75-3.75a.754.754 0 0 0-1.062 0l-3.75 3.75a.751.751 0 0 0 1.062 1.062"></path></svg>
                                                                ---)
                                                            }, {
                                                                width: "auto",
                                                                height: "auto",
                                                                lineHeight: "",
                                                                alignX: "left",
                                                                color: "#7a83a2",
                                                                value: html(---
**Neue Planversion hochladen**
                                                                ---)
                                                            }]
                                                    })
                                            },
                                            filename: {
                                                tableId: tableId("Dokumente"),
                                                fieldId: fieldId("Dokumente", "Dateiname")
                                            },
                                            image: {
                                                tableId: tableId("Dokumente"),
                                                fieldId: if ninoxApp() = "web" then
                                                    fieldId("Dokumente", "trigger_addBackgroundImage_browser")
                                                else
                                                    fieldId("Dokumente", "trigger_addBackgroundImage_app")
                                                end,
                                                width: 2000,
                                                height: 1000,
                                                widthFieldId: fieldId("Dokumente", "helper_width"),
                                                heightFieldId: fieldId("Dokumente", "helper_height")
                                            },
                                            convertSettings: {
                                                fileType: "jpg",
                                                apiKey: "something",
                                                width: 9000,
                                                height: 9000,
                                                dpi: 150
                                            },
                                            changeFieldValues: [{
                                                    fieldId: fieldId("Dokumente", "Pläne"),
                                                    value: number(current.Nr)
                                                }]
                                        })
                                }, {
                                    comment: "------------------------------- Custom Button Abbrechen ------------------------------",
                                    width: "",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "center",
                                    color: "",
                                    value: arcCustomButton({
                                            uniqueId: "Button cancel" + Nr,
                                            title: "Abbrechen",
                                            width: "",
                                            height: "",
                                            alignY: "",
                                            alignX: "",
                                            paddingX: "",
                                            paddingY: "",
                                            gap: "5px",
                                            icon: "",
                                            iconPosition: "left",
                                            fontSize: "",
                                            fontColor: "#181d2c",
                                            backgroundColor: "#7a83a2",
                                            borderColor: "#7a83a2",
                                            borderRadius: "50px",
                                            showBadge: false,
                                            badgeTitle: "",
                                            badgeColor: "",
                                            badgeBackground: "",
                                            badgeBorderColor: "",
                                            badgePosition: "",
                                            hoverActions: {
                                                fontColor: "",
                                                iconColor: "",
                                                backgroundColor: "",
                                                borderColor: "",
                                                animation: "0.25s"
                                            },
                                            actions: [{
                                                    type: "update",
                                                    recordId: current.Nr,
                                                    field: fieldId(current.Nr, "trigger_cancelUpload"),
                                                    value: "cancel"
                                                }]
                                        })
                                }]
                        })
                else
                    drawingArea
                end
            }]
    })
```

**Tadaaaaa 🧙🏼‍♀️ Das Widget Mangel-Verortung mit Pins sollte nun funktionsfähig bei dir laufen. **
<!-- /host -->


---

# Custom Sort in einer Tabelle einbinden

Source: https://www.arc-rider.com/docs/examples/customsort-einbinden


<!-- host:react -->
# Eigene Prioritätsreihenfolge in React

Prioritäten als Badge darstellen und nach einem fachlichen Rang sortieren.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Der numerische Rang in `sort.value` bestimmt die Reihenfolge. Ein zusätzliches Sort-Widget wird dafür nicht benötigt.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Sort in einer Tabelle einbinden

# Custom Sort in einer Tabelle einbinden

<iframe src="https://www.youtube.com/embed/RLm7EmMAgEM?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>Du willst deine Einträge mit dem Custom Sort direkt innerhalb der Custom Tabelle sortieren? In diesem Beitrag findest du eine detaillierte Anleitung, welche Ninox-Einstellungen du benötigst und den dazugehörigen Anwendungscode. In folgendem Beispiel wird eine Aufgabenliste (Child / Untertabelle) in einem Auftrag (Parent / Obertabelle) als Custom Table eingeblendet. Mit Custom Sort soll die Aufgaben Reihenfolge manuell bestimmt werden.

Widgets, die dafür benötigst:

- [Custom Sort](/documentation/customsort-einbinden)
- [Custom Table](/custom-table)

Ninox Einstellungen, die du benötigst:

- ein sortId Funktionsfeld in der Aufgabe (child)
- Sortierung Zahlenfeld in der Tabelle, in der die Records sortiert werden sollen
- sortItems Textfeld im Auftrag (parent)

## Anwendungscode


```javascript
let current := this;
arcCustomSort({
        uniqueId: Nr,
        editable: false,
        recordId: current.Nr,
        fieldId: "",
        direction: "horizontal",
        title: Sortierung,
        value: Sortierung,
        valuePrefix: number(Nr) + ",",
        size: "",
        color: "",
        showIconsAlways: true,
        iconStart: "",
        iconEnd: ""
    })
```

#### sortId Funktionsfeld in der Aufgabe (Child)


```javascript
let entities := Auftrag.Aufgaben;
if Sortierung != null then
    let sortValue := format(Sortierung, "000") + "-" +
        (number('Zuletzt geändert') - number(datetime(3000, 1, 1))) +
        "-" +
        number(Nr);
    number(cnt(entities[Sortierung != null and
            format(Sortierung, "000") + "-" +
                    (number('Zuletzt geändert') - number(datetime(3000, 1, 1))) +
                    "-" +
                    number(Nr) <= sortValue]))
else
    let sortValue := max(entities.Sortierung) + 1 + " + Nr;
    number(cnt(entities[max(entities.Sortierung) + 1 + " + Nr <= sortValue]))
end
```

#### sortItems Text Feld im Auftrag (Parent)

Den folgenden Code setzt du in deinem sortItems Textfeld in die Trigger nach Änderung ein.


```javascript
let current := this;
if sortItems != null then
    let splitItem := split(sortItems, ",");
    let itemNr := item(splitItem, 0);
    let itemPos := item(splitItem, 1);
    let item := first(Aufgaben[number(Nr) = number(itemNr)]);
    item.(Sortierung := number(itemPos) +
        if itemPos > item.Sortierung then
            1
        else
            0
        end);
    for item in Aufgaben order by Sortierung do
        item.(Sortierung := item.sortId)
    end;
    sortItems := null
end
```

###
<!-- /host -->


---

# Custom Table Look — Rahmen, Dark, Zeile und Spalte

Source: https://www.arc-rider.com/docs/examples/custom-table-look


<!-- host:react -->
# Tabellendesign und Dark Mode in React

Rahmen, Kopfzeile und Zellen aus einem gemeinsamen Farbsatz gestalten.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Der Schalter wechselt React-State. Leite Farben auch für eingebettete Komponenten aus demselben Theme ab; ein fremdes Theme-Paket wird nicht vorausgesetzt.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Table Look — Rahmen, Dark, Zeile und Spalte

Neue Default-Optik der Custom Table: abgerundeter Rahmen, Zeilenlinien, **keine** vertikalen Zelllinien. Alles über dieselbe `styles`-Tasche — auf der Tabelle, der Zeile und der Spalte. Keine Extra-Props für Zeilenflächen.

Ersetze `Termine` durch deine Tabelle. Die Felder sind Demo-Namen.

Gemeinsamer Rumpf für alle Varianten:

```javascript
let current := this;
let list := select Termine;
let rows := list.[{
        recordId: Nr,
        columns: [{
                field: "status",
                title: "Status",
                value: Status,
                width: "100px",
                recordId: Nr
            }, {
                field: "termin",
                title: "Termin",
                value: format(Datum, "DD.MM.YYYY"),
                width: "120px",
                recordId: Nr
            }, {
                field: "patient",
                title: "Patient",
                value: Patient,
                width: "fraction",
                recordId: Nr
            }, {
                field: "geburtsdatum",
                title: "Geburtsdatum",
                value: format(Geburtsdatum, "DD.MM.YYYY"),
                width: "140px",
                recordId: Nr
            }]
    }];
```

## Neutraler Default

Nichts Extra setzen. Header 36px, Radius 12px, Zeilenlinien an, Spaltenlinien aus.

```javascript
let data := {
        uniqueListId: "termine-look-" + Nr,
        tableId: tableId("Termine"),
        height: "400px",
        embedded: false,
        header: {
            showHeader: true,
            columns: [{
                    title: "Status",
                    width: "100px"
                }, {
                    title: "Termin",
                    width: "120px"
                }, {
                    title: "Patient",
                    width: "fraction"
                }, {
                    title: "Geburtsdatum",
                    width: "140px"
                }]
        },
        table: rows,
        emptyTable: {
            title: "Keine Termine"
        }
    };
arcCustomTable(data)
```

## In einer Card — ohne Außenrahmen

Die Table sitzt in einem Layout. Der Rahmen kommt von der Card, nicht von der Table.

```javascript
styles: {
        borders: {
            outer: false
        }
    }
```

## Klassisches Gitter

Vertikale Linien dazu, wenn die Spalten wie ein Spreadsheet gelesen werden sollen.

```javascript
styles: {
        borders: {
            columns: true
        }
    }
```

## Flush — keine Linien

Bündig, ohne Rahmen und ohne Gitter. Gut in dichten Dashboards.

```javascript
styles: {
        borders: {
            outer: false,
            columns: false,
            rows: false
        }
    }
```

## Dark

Eine Fläche für den Tisch (`styles.backgroundColor`), der Kopf über `header.backgroundColor`. Dieselbe Hierarchie wie im hellen Default — nur andere Farben.

```javascript
let data := {
        uniqueListId: "termine-dark-" + Nr,
        tableId: tableId("Termine"),
        height: "400px",
        embedded: false,
        styles: {
            backgroundColor: "#2a2822",
            fontColor: "#f5f0e6",
            borderRadius: "12px",
            borderColor: "#3f3c34",
            borders: {
                outer: true,
                columns: false,
                rows: {
                    color: "#3a372f"
                }
            }
        },
        rowHoverAction: {
            hoverActive: true,
            backgroundColor: "#35322a",
            fontColor: "#f5f0e6"
        },
        header: {
            showHeader: true,
            backgroundColor: "#1c1b16",
            fontColor: "#f5f0e6",
            columns: [{
                    title: "Status",
                    width: "100px"
                }, {
                    title: "Termin",
                    width: "120px"
                }, {
                    title: "Patient",
                    width: "fraction"
                }, {
                    title: "Geburtsdatum",
                    width: "140px"
                }]
        },
        table: rows,
        emptyTable: {
            title: "Keine Termine"
        }
    };
arcCustomTable(data)
```

## Dark — ohne Außenrahmen

Wie Dark, aber bündig in einer dunklen Card.

```javascript
styles: {
        backgroundColor: "#2a2822",
        fontColor: "#f5f0e6",
        borderColor: "#3f3c34",
        borders: {
            outer: false,
            columns: false,
            rows: {
                color: "#3a372f"
            }
        }
    },
header: {
        backgroundColor: "#1c1b16",
        fontColor: "#f5f0e6"
    }
```

## Dark — mit Spaltenlinien

```javascript
styles: {
        backgroundColor: "#2a2822",
        fontColor: "#f5f0e6",
        borderColor: "#3f3c34",
        borders: {
            outer: true,
            columns: true,
            rows: {
                color: "#3a372f"
            }
        }
    },
header: {
        backgroundColor: "#1c1b16",
        fontColor: "#f5f0e6"
    }
```

## Eine Zeile und eine Spalte

Dieselbe `styles`-Tasche eine Ebene tiefer. Spalte gewinnt gegen Zeile, Zeile gegen Tabelle.

```javascript
table: list.[{
        recordId: Nr,
        styles: if Status = "Neu" then {
                backgroundColor: "#f4f4f5"
            } end,
        columns: [{
                field: "status",
                title: "Status",
                value: Status,
                width: "100px",
                recordId: Nr
            }, {
                field: "termin",
                title: "Termin",
                value: format(Datum, "DD.MM.YYYY"),
                width: "120px",
                recordId: Nr
            }, {
                field: "patient",
                title: "Patient",
                value: Patient,
                width: "fraction",
                recordId: Nr,
                styles: if Status = "Neu" then {
                        backgroundColor: "#e4e4e7",
                        fontWeight: "600"
                    } end
            }, {
                field: "geburtsdatum",
                title: "Geburtsdatum",
                value: format(Geburtsdatum, "DD.MM.YYYY"),
                width: "140px",
                recordId: Nr
            }]
    }]
```

`rowColor` bleibt als alter Alias. Neu immer `styles.backgroundColor` auf der passenden Ebene.
<!-- /host -->


---

# Custom Table mit Mini Widgets

Source: https://www.arc-rider.com/docs/examples/custom-table-mit-mini-widgets


<!-- host:react -->
# Auftragsliste mit Suche und Status in React

Eine Liste filtern, Status und Fortschritt als React-Komponenten in Zellen darstellen und einen Auftrag auswählen.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Der Filter erzeugt eine neue Zeilenliste. Die Auswahl verwendet eine stabile Auftrags-ID. Ersetze die Beispieldaten durch Daten aus deiner API.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Custom Table mit Mini Widgets

# Mehr Übersicht in Tabellen: Mini Widgets direkt in der Custom Table

![](https://framerusercontent.com/images/Gipfc03JpgpGTPrqL4RJ0ONktE.png)

In diesem Beitrag zeigen wir euch ein praxisnahes und komplexes Beispiel für eine **Custom Table**, die eure **Aufgabenverwaltung in Ninox** deutlich übersichtlicher und interaktiver macht. Die Tabelle gruppiert Aufgaben nach Aufträgen und kombiniert leistungsstarke Funktionen mit einer modernen Darstellung.

Dank der integrierten **Mini Widgets** – darunter [Checkbox](/documentation/check-box), [Input](/documentation/input), [Progress Bar](/documentation/progress-bar), [Button](/documentation/buttons), [Select](/documentation/select), [Icon](/documentation/custom-icon) und [Pagination](/documentation/pagination) – lässt sich die Tabelle direkt bedienen, ohne die Ansicht verlassen zu müssen. Ideal für alle, die Effizienz und Benutzerfreundlichkeit in ihren Workflows kombinieren möchten.

## Aufgabenverwaltung leicht gemacht

Mit unserer Custom Table verwaltet ihr Aufgaben so einfach und effizient wie nie zuvor. Dank der Gruppierung nach Aufträgen behaltet ihr stets den Überblick – und das ist erst der Anfang.

## ✅ Aufgaben abhaken leicht gemacht

Per integrierter [Checkbox](/documentation/check-box) markiert ihr erledigte Aufgaben direkt in der Tabelle. Ein visuelles Feedback zeigt euch sofort, was bereits geschafft ist.

## 📝 Beschreibungen direkt editieren

In der Spalte „Beschreibung“ findet ihr mehrzeilige [Inputfelder](/documentation/input). Damit könnt ihr Aufgaben direkt bearbeiten – ohne zusätzliche Klicks oder das Öffnen einzelner Datensätze.

## 📅 Termine schnell anpassen

Mit dem eingebauten Datumsfeld aktualisiert ihr Fälligkeiten im Handumdrehen. Einfach das neue Datum auswählen – fertig.

## 📊 Fortschritt immer im Blick

Die integrierte [ProgressBar](/documentation/progress-bar) zeigt euch auf einen Blick, wie weit ihr mit den Aufgaben seid – farblich visualisiert und jederzeit aktuell.

## ➕ Unteraufgaben direkt hinzufügen

Per [Button](/documentation/buttons) erstellt ihr neue Unteraufgaben in einem Ninox-Popup. So lassen sich Aufgaben flexibel verfeinern und strukturieren.

## 🔄 Status einfach umstellen

Ein [Dropdown](/documentation/select)-Menü ermöglicht die direkte Änderung des Aufgabenstatus – schnell, intuitiv und ohne Umwege.

## 🗑️ Aufräumen leicht gemacht

Ein Klick auf das [Löschen-Icon](/user/account/icons) entfernt überflüssige Aufgaben direkt aus der Tabelle. Schnell, effizient und ohne Extra-Schritte.

## 🎨 Farbige Übersicht

Die dynamische groupRowColor-Funktion färbt die Zeilen je nach Fortschritt automatisch ein – für maximale Übersicht und visuelle Klarheit.

### ⚙️ Automationen weiter nutzen

Die Widgets greifen nicht in eure Datenstruktur ein – ihr könnt weiterhin alle gewohnten Automationen in Ninox nutzen. Zum Beispiel: Setzt automatisch das Datum auf `today()` bei Abschluss einer Aufgabe – alles über „Trigger nach Änderung“ steuerbar.

## Fazit

Mit dieser **Custom Table** bringt ihr eure Aufgabenverwaltung auf ein neues Level. Interaktive Mini Widgets wie Checkbox, Input, Progress Bar, Button, Select, Icon und Pagination machen eure Tabelle zum leistungsstarken UI-Element.

🚀 **Effizienz trifft Übersicht – direkt in Ninox.**

## Anwendungscode des Beispiels


```javascript
let current := this;
let list := (flteredList_Aufgaben[cnt(Auftrag.Aufgaben) > 5] order by cnt(Auftrag.Aufgaben)); //Ihr könnt euch Listen in extra Formel-Feldern vorfiltern, damit der Code nicht so lang wird
let maxEntries := 'Einträge pro Seite'; // Hilfsfeld Zahl
let currentPage := 'Aktuelle Seite'; // Hilfsfeld Zahl
let paginatedList := unique(record(Aufgaben,0))[!= 0];
for listItem in slice(list.Nr, maxEntries * (currentPage - 1), maxEntries * currentPage) do
    paginatedList := unique(paginatedList, record(Aufgaben,listItem))
end;
let data := {
        uniqueListId: "Aufgaben Demo 1",
        tableId: tableId(first(list)),
        height: "600px",
        width: "100px",
        groupedBy: "Aufgabe",
        groupsCollapsed: false,
        embedded: false,
        table: paginatedList.[{
                recordId: Nr,
                rowColor: "",
                rowHeight: "auto",
                rowPaddingY: "10px",
                groupRowColor: let currentRecord := Nr;
                if cnt(list[Checkliste.Nr = currentRecord.Checkliste.Nr and Erledigt = true]) = cnt(list[Checkliste.Nr = currentRecord.Checkliste.Nr]) then
                    "#dcf2de"
                else
                    "#eee"
                end,
                columns: [{
                        field: "Erledigt",
                        title: arcCheckBox({
                                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({
                                value: Erledigt
                            }),
                        width: "40px",
                        align: "center",
                        fixed: "left",
                        actions: [{
                                recordId: Nr,
                                type: "update",
                                field: "G",
                                value: if Erledigt = true then null else true end,
                                headerAction: true
                            }],
                        groupValue: arcCustomIcon({
                                name: "caret-circle-double-down-fill"
                            })
                    }, {
                        field: "Aufgabe",
                        title: "Aufgabe",
                        width: "",
                        value: replace(Aufgabe, ">", "❯"),
                        actions: [{
                                recordId: Nr,
                                type: "popup",
                                showPopupButton: true
                            }],
                        groupValue: html("**" + Auftrag.Titel + "**"),
                        groupByValue: Auftrag.Nr
                    }, {
                        field: "'Erledigt am'",
                        title: "Beschreibung",
                        value: arcCustomInput({
                                uniqueId: "Mein-Textarea-" + Nr,
                                recordId: Nr,
                                fieldId: "B",
                                title: Beschreibung,
                                value: Beschreibung,
                                type: "textarea",
                                embedded: true,
                                disabled: false,
                                width: "",
                                height: "auto",
                                minHeight: "40px",
                                fontColor: "",
                                fontSize: "",
                                fontWeight: "",
                                backgroundColor: "",
                                borderWidth: "",
                                borderColor: "",
                                borderRadius: "",
                                placeholderSettings: {
                                    value: "Beschreibe die Aufgabe..."
                                },
                                focusAction: {
                                    width: "",
                                    showFocusOutline: "",
                                    outlineWidth: "",
                                    outlineColor: ""
                                },
                                alignX: "left",
                                paddingX: ""
                            }),
                        align: "left",
                        width: "280px"
                    }, {
                        field: "'Erledigt am'",
                        title: "Erledigt am",
                        value: arcCustomInput({
                                uniqueId: "Mein-Input-" + Nr,
                                recordId: Nr,
                                fieldId: "A1",
                                value: Startdatum,
                                type: "date",
                                embedded: true,
                                disabled: false,
                                width: "",
                                height: "",
                                fontColor: "",
                                fontSize: "",
                                fontWeight: "",
                                backgroundColor: "#fff6d8",
                                borderWidth: "",
                                borderColor: "",
                                borderRadius: "",
                                placeholderSettings: {
                                    value: "Datum eintragen",
                                    fontColor: "#e9595c",
                                    backgroundColor: "#fff7f7"
                                },
                                focusAction: {
                                    width: "",
                                    showFocusOutline: "",
                                    outlineWidth: "",
                                    outlineColor: ""
                                },
                                alignX: "left",
                                paddingX: ""
                            }),
                        align: "left",
                        width: "180px"
                    }, {
                        field: "Aufgaben",
                        title: "Aufgaben",
                        value: arcCustomProgressBar({
                                uniqueId: "",
                                width: "",
                                fontSize: "",
                                fontColor: "",
                                backgroundColor: "",
                                progressColor: "",
                                valueTotal: cnt(Unteraufgaben),
                                valueProgress: cnt(Unteraufgaben[Erledigt = true]),
                                valueText: cnt(Unteraufgaben[Erledigt = true]) + "/" + cnt(Unteraufgaben)
                            }),
                        align: "left",
                        width: "150px",
                        groupValue: arcCustomProgressBar({
                                uniqueId: "Erledigte Aufgaben",
                                title: "",
                                width: "",
                                fontSize: "",
                                fontColor: "",
                                backgroundColor: "#fff",
                                progressColor: "",
                                valueTotal: cnt(Auftrag.Aufgaben),
                                valueProgress: cnt(Auftrag.Aufgaben[Erledigt = true]),
                                valueText: cnt(Auftrag.Aufgaben[Erledigt = true]) + "/" + cnt(Auftrag.Aufgaben)
                            })
                    }, {
                        field: "",
                        title: "",
                        value: arcCustomButton({
                                uniqueId: "Unteraufgabe erstellen" + Nr,
                                title: "Unteraufgabe",
                                width: "100%",
                                icon: arcCustomIcon({
                                        name: "plus-bold",
                                        color: "#0062AA"
                                    }),
                                fontSize: "",
                                fontColor: "#0062AA",
                                iconColor: "#0062AA",
                                backgroundColor: "#0062AA33",
                                borderColor: "#0062AA",
                                borderRadius: "50px",
                                showBadge: false,
                                badgeTitle: cnt(Unteraufgaben),
                                badgeColor: "",
                                badgeBackground: "",
                                badgeBorderColor: "",
                                badgePosition: "",
                                hoverActions: {
                                    fontColor: "#ffffff",
                                    iconColor: "#ffffff",
                                    backgroundColor: "#0062AA",
                                    borderColor: "#0062AA",
                                    animation: "0.5s"
                                },
                                actions: [{
                                        type: "create",
                                        tableId: "B",
                                        popup: true,
                                        changeFieldValues: [{
                                                fieldId: "S",
                                                value: number(Nr)
                                            }]
                                    }]
                            }),
                        align: "left",
                        width: "180px"
                    }, {
                        field: "Status",
                        title: "Status",
                        value: arcCustomSelect({
                                uniqueId: "Status" + Nr,
                                currentValue: text(Status),
                                recordId: Nr,
                                field: "Q",
                                width: "100%",
                                height: "30px",
                                fontSize: "10px",
                                placeholder: "Status wählen",
                                emptyValue: "Zurücksetzen",
                                items: let id := Nr;
                                (select Status_Aufgabe).[{
                                        title: Bezeichnung,
                                        active: number(id.Status) = number(Nr),
                                        value: number(Nr)
                                    }]
                            }),
                        align: "right",
                        width: "150px"
                    }, {
                        field: "delete",
                        title: arcCustomIcon({
                                name: "trash"
                            }),
                        width: "40px",
                        align: "center",
                        value: arcCustomIcon({
                                name: "trash"
                            }),
                        actions: [{
                                recordId: Nr,
                                type: "delete"
                            }]
                    }]
            }],
        footer: {
            showFooter: true,
            showActionButton: false,
            actionButtonTitle: "Neue Aufgabe hinzufügen",
            leftSideContent: arcCustomButton({
                    uniqueId: "Button popUp" + Nr,
                    title: "Neue Checkliste hinzufügen",
                    width: "",
                    icon: arcCustomIcon({
                            name: "plus-bold",
                            color: "#0062AA"
                        }),
                    fontSize: "",
                    fontColor: "#0062AA",
                    iconColor: "#0062AA",
                    backgroundColor: "#0062AA33",
                    borderColor: "#0062AA",
                    borderRadius: "50px",
                    showBadge: false,
                    badgeTitle: "",
                    badgeColor: "",
                    badgeBackground: "",
                    badgeBorderColor: "",
                    badgePosition: "",
                    hoverActions: {
                        fontColor: "#ffffff",
                        iconColor: "#ffffff",
                        backgroundColor: "#0062AA",
                        borderColor: "#0062AA",
                        animation: "0.8s"
                    },
                    actions: [{
                            type: "create",
                            tableId: "C",
                            popup: true,
                            changeFieldValues: [{
                                    fieldId: "",
                                    value: ""
                                }, {
                                    fieldId: "",
                                    value: ""
                                }]
                        }]
                }),
            rightSideContent: arcCustomPagination({
                    uniqueId: Nr,
                    editable: true,
                    recordId: current.Nr,
                    fieldId: "P",
                    direction: "horizontal",
                    title: current.'Aktuelle Seite',
                    value: current.'Aktuelle Seite',
                    total: ceil(cnt(list) / maxEntries),
                    totalPrefix: " von "
                })
        }
    };
arcCustomTable(data)
```
<!-- /host -->


---

# Dashboardansicht mit Grid

Source: https://www.arc-rider.com/docs/examples/dashboardansicht-mit-grid


<!-- host:react -->
# Dashboard mit Arc Grid in React

Kennzahlen, Fortschritt und eine Tabelle in einem responsiven Dashboard anordnen.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel

<!-- react-example: grid-02-dashboard_spans.tsx -->
```tsx
import { useState } from 'react';
import {
  ArcWidgetBadge,
  ArcWidgetGrid,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

export default function Example() {
  const [selected, setSelected] = useState('none');
  const ids = ['revenue', 'orders', 'chart', 'inbox'];

  // `columnSpan` and `rowSpan` make a block wider or taller than one cell.
  // The chart block takes two columns and two rows; the neighbours flow around it.
  return (
    <ArcWidgetGrid
      onBlockClick={(index) => setSelected(ids[index] ?? 'none')}
      data={{
        columns: 4,
        gap: '12px',
        paddingX: '16px',
        paddingY: '16px',
        backgroundColor: '#F4F4F5',
        blockDefaults: {
          clickable: true,
          paddingX: '16px',
          paddingY: '16px',
          backgroundColor: '#FFFFFF',
          border: { color: '#D4D4D8', radius: '12px' },
        },
        blocks: [
          {
            blockId: 'revenue',
            value: <ArcWidgetText data={{ value: 'Revenue EUR 24,300', fontWeight: '700' }} />,
          },
          {
            blockId: 'orders',
            value: <ArcWidgetText data={{ value: 'Orders 128', fontWeight: '700' }} />,
          },
          {
            blockId: 'chart',
            columnSpan: 2,
            rowSpan: 2,
            alignX: 'center',
            alignY: 'center',
            value: 'Chart area (2 x 2)',
          },
          {
            blockId: 'inbox',
            columnSpan: 2,
            value: (
              <ArcWidgetBadge
                data={{
                  value: `Selected: ${selected}`,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## So funktioniert es

`ArcWidgetGrid` ordnet die Kacheln in vier Spalten an. Die Diagramm-Kachel nutzt `columnSpan: 2` und `rowSpan: 2`; die übrigen Kacheln fließen um sie herum. Ohne `columns` würde das Grid so viele Spalten anlegen, wie die Breite zulässt, das Dashboard passt sich so ohne Breakpoints an den Bildschirm an. Kacheln mit `clickable: true` melden ihren Index über `onBlockClick`.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Dashboardansicht mit Grid

# Dashboards neu gedacht: Grid-Layout in Ninox

Mit dem `arcCustomGrid`-Widget lassen sich individuelle Dashboards und Übersichtsseiten in einem flexiblen [Grid](/documentation/custom-grid)-Layout gestalten.

Kombiniere beliebige Widgets, Texte oder [Layout](/documentation/custom-layout)-Blöcke und positioniere sie pixelgenau – ob im internen Cockpit oder für externe Kundenansichten.

Das folgende Beispiel zeigt ein einfaches Dashboard-Setup mit drei Spalten und mehreren [Cards](/documentation/cards), Texten und [Icons](/documentation/custom-icon):

<iframe src="https://www.youtube.com/embed/Ea8r5bi_oJM?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1&loop=1&playlist=Ea8r5bi_oJM" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>## Anwendungscode des Beispiels


```javascript
let current := this;
arcCustomLayout({
        uniqueId: Nr,
        embedded: false,
        fullscreen: true,
        direction: "horizontal",
        alignX: "center",
        alignY: "center",
        width: "",
        height: "700px",
        gap: "50px",
        backgroundColor: "#000000",
        paddingY: "30px",
        paddingX: "30px",
        blocks: [{
                width: "",
                height: "100%",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "    overflow-y: scroll;",
                value: arcCustomGrid({
                        uniqueId: "",
                        width: "100%",
                        height: "100%",
                        columns: "auto-fit",
                        columnWidth: "250px",
                        gap: "10px",
                        paddingY: "20px",
                        paddingX: "20px",
                        styles: "/*grid-template-columns: repeat(auto-fit, 1fr);*/",
                        blocks: [{
                                blockId: "",
                                width: "",
                                height: "100%",
                                alignX: "center",
                                alignY: "center",
                                paddingY: "",
                                paddingX: "",
                                backgroundColor: "",
                                lineHeight: "",
                                styles: "overflow-y: scroll;",
                                value: arcCustomGrid({
                                        uniqueId: "Dashboard Grid",
                                        styles: "",
                                        width: "100%",
                                        height: "100%",
                                        columns: "auto-fill",
                                        columnWidth: "200px",
                                        gap: "10px",
                                        paddingY: "",
                                        paddingX: "",
                                        blocks: [{
                                                blockId: "--------- GRID BLOCK 1 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                clickAction: {
                                                    type: "fullscreen",
                                                    recordId: current.Nr
                                                },
                                                value: arcCustomCard({
                                                        uniqueId: "Card 1",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "clipboard-text",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#FF7403",
                                                                backgroundColor: "#FEEFC4"
                                                            }),
                                                        title: "Aufgaben",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }, {
                                                blockId: "--------- GRID BLOCK 2 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomCard({
                                                        uniqueId: "Card 2",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "users",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#C637E4",
                                                                backgroundColor: "#FAE6FF"
                                                            }),
                                                        title: "Mitarbeiter",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }, {
                                                blockId: "--------- GRID BLOCK 3 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomCard({
                                                        uniqueId: "Card 3",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "folder",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#42B000",
                                                                backgroundColor: "#DEFCCB"
                                                            }),
                                                        title: "Buchhaltung",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }, {
                                                blockId: "--------- GRID BLOCK 4 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomCard({
                                                        uniqueId: "Card 4",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "clock",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#944810",
                                                                backgroundColor: "#ECD8C8"
                                                            }),
                                                        title: "Zeiterfassung",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }, {
                                                blockId: "--------- GRID BLOCK 5 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomCard({
                                                        uniqueId: "Card 5",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "buildings",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#E80102",
                                                                backgroundColor: "#FFEDEC"
                                                            }),
                                                        title: "Kunden",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }, {
                                                blockId: "--------- GRID BLOCK 6 ----------",
                                                alignX: "center",
                                                alignY: "right",
                                                height: "100%",
                                                width: "100%",
                                                value: arcCustomCard({
                                                        uniqueId: "Card 6",
                                                        backgroundColor: "#fff",
                                                        width: "100%",
                                                        height: "100%",
                                                        borderRadius: "10px",
                                                        icon: arcCustomIcon({
                                                                name: "file",
                                                                containerSize: "50px",
                                                                borderSize: "1px",
                                                                borderColor: "",
                                                                iconSize: "25px",
                                                                borderRadius: "50px",
                                                                color: "#028BFF",
                                                                backgroundColor: "#E1F1FF"
                                                            }),
                                                        title: "Dokumente",
                                                        value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
                                                    })
                                            }]
                                    })
                            }, {
                                blockId: "",
                                width: "",
                                height: "100%",
                                alignX: "center",
                                alignY: "center",
                                paddingY: "",
                                paddingX: "",
                                backgroundColor: "",
                                lineHeight: "",
                                styles: "",
                                value: arcCustomCard({
                                        uniqueId: "Card 6",
                                        backgroundColor: "#fff",
                                        width: "100%",
                                        height: "100%",
                                        borderRadius: "10px",
                                        icon: arcCustomIcon({
                                                name: "kanban",
                                                containerSize: "50px",
                                                borderSize: "1px",
                                                borderColor: "",
                                                iconSize: "25px",
                                                borderRadius: "50px",
                                                color: "#028BFF",
                                                backgroundColor: "#E1F1FF"
                                            }),
                                        title: "Projekte",
                                        value: "I'm baby pitchfork williamsburg twee asymmetrical direct trade, fam blue bottle kombucha slow-carb franzen. Poke gochujang pop-up meditation. Waistcoat vinyl vice small batch photo booth migas iPhone pug kale chips jean shorts poutine. Intelligentsia dreamcatcher plaid, prism fashion axe kale chips typewriter marxism wayfarers enamel pin readymade chia. Pok pok mixtape everyday carry cupping, poke slow-carb skateboard."
                                    })
                            }]
                    })
            }]
    })
```
<!-- /host -->


---

# Datenaufnahme in Schritten

Source: https://www.arc-rider.com/docs/examples/datenaufnahme-in-schritten


<!-- host:react -->
# Ein Formular in Schritten in React

Eingabe, Prüfung und Abschluss durch React-State verbinden.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Vor dem nächsten Schritt wird die Pflichtangabe geprüft. Das Steps-Widget zeigt den Zustand; Fachlogik und Navigation bleiben in der Anwendung.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Datenaufnahme in Schritten

# Datenaufnahme in Schritten

<iframe src="https://www.youtube.com/embed/SXJU6ZosPhA?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>Wenn du im Außendienst tätig bist und schnell sowie unkompliziert Daten erfassen musst, ist eine klare und gut strukturierte Eingabemaske unerlässlich. Besonders bei einer großen Anzahl an zu erfassenden Feldern ist es sinnvoll, die Dateneingabe in mehrere Schritte zu unterteilen. Auf diese Weise wird der Benutzer nicht überfordert und kann schneller sowie geordneter die notwendigen Informationen eingeben.

In diesem Beitrag zeigen wir dir, wie du mit einfachen Tricks und nützlichen Widgets eine benutzerfreundliche Oberfläche gestalten kannst, die dir die Datenerfassung erheblich erleichtert. Erfahre, wie du die Effizienz deines Arbeitsalltags steigerst und dabei stets den Überblick behältst.

 Widget: [ Custom Layout ](/documentation/custom-layout)mit integrierten Mini Widgets:  [Input](/documentation/input), [Button](/documentation/buttons), [Text](/documentation/text) und  [Icon](/documentation/custom-icon).

## Anwendungscode Teil 1 Layouts & Überschriften


```javascript
let current := this;
let namenLayout := arcCustomLayout({
            uniqueId: "namenLayout " + Nr,
            embedded: true,
            fullscreen: false,
            direction: "vertical",
            alignX: "center",
            alignY: "center",
            width: "490px",
            height: "100%",
            gap: "10px",
            backgroundColor: "",
            paddingY: "",
            paddingX: "",
            blocks: [{
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    styles: "",
                    value: arcCustomInput({
                            uniqueId: "vorname" + Nr,
                            recordId: Nr,
                            fieldId: "G",
                            title: text(Vorname),
                            value: text(Vorname),
                            type: "text",
                            embedded: true,
                            disabled: false,
                            width: "100%",
                            height: "40px",
                            alignX: "left",
                            paddingY: "",
                            paddingX: "",
                            fontColor: "",
                            fontSize: "",
                            fontWeight: "",
                            backgroundColor: "#F0F0F0",
                            borderWidth: "",
                            borderColor: "",
                            borderRadius: "",
                            focusAction: {
                                width: "",
                                showFocusOutline: "",
                                outlineWidth: "",
                                outlineColor: ""
                            },
                            labelSettings: {
                                title: "Vorname",
                                fontSize: "",
                                alignX: "",
                                gap: "10px"
                            }
                        })
                }, {
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    value: arcCustomInput({
                            uniqueId: "Nachname" + Nr,
                            recordId: Nr,
                            fieldId: "H",
                            title: text(Nachname),
                            value: text(Nachname),
                            type: "text",
                            embedded: true,
                            disabled: false,
                            width: "100%",
                            height: "40px",
                            alignX: "left",
                            paddingY: "",
                            paddingX: "",
                            fontColor: "",
                            fontSize: "",
                            fontWeight: "",
                            backgroundColor: "#F0F0F0",
                            borderWidth: "",
                            borderColor: "",
                            borderRadius: "",
                            focusAction: {
                                width: "",
                                showFocusOutline: "",
                                outlineWidth: "",
                                outlineColor: ""
                            },
                            labelSettings: {
                                title: "Nachname",
                                fontSize: "",
                                alignX: "",
                                gap: "10px"
                            }
                        })
                }]
        });
let adressLayout := arcCustomLayout({
            uniqueId: "adressLayout " + Nr,
            embedded: true,
            fullscreen: false,
            direction: "vertical",
            alignX: "center",
            alignY: "center",
            width: "490px",
            height: "100%",
            gap: "10px",
            backgroundColor: "",
            paddingY: "",
            paddingX: "",
            blocks: [{
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    styles: "",
                    value: arcCustomInput({
                            uniqueId: "Straße u Hausnr" + Nr,
                            recordId: Nr,
                            fieldId: "I",
                            title: text('Straße + Hausnr'),
                            value: text('Straße + Hausnr'),
                            type: "text",
                            embedded: true,
                            disabled: false,
                            width: "100%",
                            height: "40px",
                            alignX: "left",
                            paddingY: "",
                            paddingX: "",
                            fontColor: "",
                            fontSize: "",
                            fontWeight: "",
                            backgroundColor: "#F0F0F0",
                            borderWidth: "",
                            borderColor: "",
                            borderRadius: "",
                            focusAction: {
                                width: "",
                                showFocusOutline: "",
                                outlineWidth: "",
                                outlineColor: ""
                            },
                            labelSettings: {
                                title: "Straße & Hausnummer",
                                fontSize: "",
                                alignX: "",
                                gap: "10px"
                            }
                        })
                }, {
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    value: arcCustomLayout({
                            uniqueId: "adressZeile PLZ und Ort " + Nr,
                            embedded: true,
                            fullscreen: false,
                            direction: "horizontal",
                            alignX: "left",
                            alignY: "center",
                            width: "",
                            height: "",
                            gap: "10px",
                            backgroundColor: "",
                            paddingY: "",
                            paddingX: "",
                            blocks: [{
                                    width: "200px",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "left",
                                    color: "",
                                    styles: "",
                                    value: arcCustomInput({
                                            uniqueId: "PLZ" + Nr,
                                            recordId: Nr,
                                            fieldId: "J",
                                            title: text(PLZ),
                                            value: text(PLZ),
                                            type: "text",
                                            embedded: true,
                                            disabled: false,
                                            width: "100%",
                                            height: "40px",
                                            alignX: "left",
                                            paddingY: "",
                                            paddingX: "",
                                            fontColor: "",
                                            fontSize: "",
                                            fontWeight: "",
                                            backgroundColor: "#F0F0F0",
                                            borderWidth: "",
                                            borderColor: "",
                                            borderRadius: "",
                                            focusAction: {
                                                width: "",
                                                showFocusOutline: "",
                                                outlineWidth: "",
                                                outlineColor: ""
                                            },
                                            labelSettings: {
                                                title: "PLZ",
                                                fontSize: "",
                                                alignX: "",
                                                gap: "10px"
                                            }
                                        })
                                }, {
                                    width: "",
                                    height: "auto",
                                    lineHeight: "",
                                    alignX: "left",
                                    color: "",
                                    value: arcCustomInput({
                                            uniqueId: "Ort" + Nr,
                                            recordId: Nr,
                                            fieldId: "K",
                                            title: text(Ort),
                                            value: text(Ort),
                                            type: "text",
                                            embedded: true,
                                            disabled: false,
                                            width: "100%",
                                            height: "40px",
                                            alignX: "left",
                                            paddingY: "",
                                            paddingX: "",
                                            fontColor: "",
                                            fontSize: "",
                                            fontWeight: "",
                                            backgroundColor: "#F0F0F0",
                                            borderWidth: "",
                                            borderColor: "",
                                            borderRadius: "",
                                            focusAction: {
                                                width: "",
                                                showFocusOutline: "",
                                                outlineWidth: "",
                                                outlineColor: ""
                                            },
                                            labelSettings: {
                                                title: "Ort",
                                                fontSize: "",
                                                alignX: "",
                                                gap: "10px"
                                            }
                                        })
                                }]
                        })
                }]
        });
let kontaktLayout := arcCustomLayout({
            uniqueId: "kontaktLayout " + Nr,
            embedded: true,
            fullscreen: false,
            direction: "vertical",
            alignX: "center",
            alignY: "center",
            width: "490px",
            height: "100%",
            gap: "10px",
            backgroundColor: "",
            paddingY: "",
            paddingX: "",
            blocks: [{
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    styles: "",
                    value: arcCustomInput({
                            uniqueId: "kontakt" + Nr,
                            recordId: Nr,
                            fieldId: "N",
                            title: text(Telefon),
                            value: text(Telefon),
                            type: "text",
                            embedded: true,
                            disabled: false,
                            width: "100%",
                            height: "40px",
                            alignX: "left",
                            paddingY: "",
                            paddingX: "",
                            fontColor: "",
                            fontSize: "",
                            fontWeight: "",
                            backgroundColor: "#F0F0F0",
                            borderWidth: "",
                            borderColor: "",
                            borderRadius: "",
                            focusAction: {
                                width: "",
                                showFocusOutline: "",
                                outlineWidth: "",
                                outlineColor: ""
                            },
                            labelSettings: {
                                title: "Telefon",
                                fontSize: "",
                                alignX: "",
                                gap: "10px"
                            }
                        })
                }, {
                    width: "",
                    height: "auto",
                    lineHeight: "",
                    alignX: "center",
                    color: "",
                    value: arcCustomInput({
                            uniqueId: "Ansprechpartner" + Nr,
                            recordId: Nr,
                            fieldId: "O",
                            title: text('E-Mail'),
                            value: text('E-Mail'),
                            type: "text",
                            embedded: true,
                            disabled: false,
                            width: "100%",
                            height: "40px",
                            alignX: "left",
                            paddingY: "",
                            paddingX: "",
                            fontColor: "",
                            fontSize: "",
                            fontWeight: "",
                            backgroundColor: "#F0F0F0",
                            borderWidth: "",
                            borderColor: "",
                            borderRadius: "",
                            focusAction: {
                                width: "",
                                showFocusOutline: "",
                                outlineWidth: "",
                                outlineColor: ""
                            },
                            labelSettings: {
                                title: "E-Mail",
                                fontSize: "",
                                alignX: "",
                                gap: "10px"
                            }
                        })
                }]
        });
arcCustomLayout({
        uniqueId: "Content Aufnahme " + Nr,
        embedded: false,
        fullscreen: false,
        direction: "vertical",
        alignX: "center",
        alignY: "top",
        width: "",
        height: "450px",
        gap: "",
        backgroundColor: "",
        paddingY: "",
        paddingX: "",
        blocks: [{
                width: "",
                height: "100px",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: arcCustomText({
                        uniqueId: "headline" + Nr,
                        embedded: true,
                        width: "",
                        height: "",
                        alignY: "",
                        alignX: "center",
                        fontSize: "27px",
                        fontWeight: "700",
                        fontColor: "",
                        lineHeight: "",
                        textWrap: "",
                        textScroll: "",
                        textAlign: "",
                        textDirection: "horizontal",
                        textDecoration: {
                            type: "",
                            style: "",
                            color: "",
                            thickness: ""
                        },
                        value: if Menu = "1" then
                            "Name"
                        else
                            if Menu = "2" then
                                "Adresse"
                            else
                                if Menu = "3" then "Kontakt" end
                            end
                        end
                    })
            }, {
                width: "",
                height: "fraction",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: if Menu = "1" then
                    namenLayout
                else
                    if Menu = "2" then
                        adressLayout
                    else
                        if Menu = "3" then kontaktLayout end
                    end
                end
            }, {
                width: "",
                height: "100px",
                lineHeight: "",
                alignX: "center",
                color: "",
                styles: "",
                value: menuSteps
            }]
    })
```

## Anwendungscode Teil 2 Menü Buttons


```javascript
let current := this;
function buttonSubmenu(data : any) do
    arcCustomButton({
            uniqueId: "Button submenu " + data.uniqueId,
            title: data.title,
            width: "",
            height: "",
            alignY: "",
            alignX: "",
            icon: arcCustomIcon({
                    name: "check-circle-fill",
                    color: if data.completed = true then
                        "#b5db3b"
                    else
                        "#ddd"
                    end,
                    iconSize: "19px",
                    containerSize: "21px",
                    backgroundColor: "#fff",
                    borderSize: "",
                    borderColor: "#fff",
                    borderRadius: "50%"
                }),
            fontSize: "",
            fontColor: if data.active = true then "#fff" else "#777" end,
            backgroundColor: if data.active = true then
                "#4970FF"
            else
                if data.completed = true then
                    "#f4fcd9"
                else
                    "#fff"
                end
            end,
            borderColor: if data.active = true then "#4970FF" else "#777" end,
            borderRadius: "18px"
        })
end;
let menuList := [{
            title: "Name",
            value: "1",
            showLine: true,
            completed: Vorname != null and Nachname != null
        }, {
            title: "Adresse",
            value: "2",
            showLine: true,
            completed: 'Straße + Hausnr' != null and PLZ != null and Ort != null
        }, {
            title: "Kontakt",
            value: "3",
            showLine: true,
            completed: Telefon != null and 'E-Mail' != null
        }];
arcCustomLayout({
        uniqueId: "menuSteps " + Nr,
        embedded: true,
        fullscreen: false,
        direction: "horizontal",
        alignX: "center",
        alignY: "center",
        width: "",
        height: "",
        gap: "5px",
        backgroundColor: "",
        paddingY: "",
        paddingX: "",
        blocks: menuList.[{
                width: "auto",
                height: "auto",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                clickAction: {
                    type: "update",
                    recordId: current.Nr,
                    field: "M",
                    value: value
                },
                value: buttonSubmenu({
                        uniqueId: "buttonSubmenu " + value + " " + Nr,
                        title: title,
                        value: value,
                        active: current.Menu = value,
                        completed: completed
                    })
            }]
    })
```
<!-- /host -->


---

# Image-Slider

Source: https://www.arc-rider.com/docs/examples/image-slider


<!-- host:react -->
# Bildergalerie mit Slideshow in React

Zwei selbst erzeugte Bilder anzeigen und den aktiven Slide ausgeben.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

`items[].value` ist hier ein HTML-String mit einem Bild. Slideshow unterstützt aktuell keine JSX-Slots. Fremde Texte oder URLs dürfen nicht ungeprüft in HTML eingesetzt werden.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Image-Slider

# 📸 Image-Slider in Ninox

![](https://framerusercontent.com/images/Zrw6W9ePdP2qQQkzRtUz8KLZgA.png)

So baust du deinen individuell gestalteten Bildwechsler – ganz ohne externe Galerie-Tools.

Du möchtest mehrere Bilder aus einer Tabelle übersichtlich und interaktiv durchblättern? In diesem Beitrag zeigen wir dir Schritt für Schritt, welche Widgets und Ninox-Einstellungen du brauchst – inklusive Beispielcode zur Umsetzung.

## 🧩 Benötigte Widgets

- [Custom Layout](/documentation/custom-layout)
- [Custom Image](/documentation/images)
- [Custom Text](/documentation/text)
- [Button](/documentation/buttons)

## 📁 Aufbau deiner Tabelle

Du brauchst eine Tabelle mit folgenden Feldern:

<figure><table><tbody><tr><th>Feldname

</th><th>Typ

</th></tr><tr><td>`Bild`

</td><td>Dokumenten-/Bild-Feld

</td></tr><tr><td>`shareUrl`

</td><td>URL-Feld

</td></tr><tr><td>`sortId`

</td><td>Zahlenfeld (zur Sortierung)

</td></tr><tr><td>`Beschreibung`

</td><td>Text-Feld

</td></tr><tr><td>`currentImage`

</td><td>Hilfsfeld (Text), z. B. im Layout

</td></tr></tbody></table></figure>💡** Tipp:** Das Feld `currentImage` dient der Steuerung des aktuell angezeigten Bilds im Slider.

![](https://framerusercontent.com/images/lm9TX63iMrK06COA4FkH9bpn48.png)

## 🛠️ Vorgehensweise

Sobald du die oben genannten Voraussetzungen umgesetzt hast, kannst du mit dem eigentlichen Aufbau des Image-Sliders beginnen.

### 1. Code einfügen

Der Anwendungscode für den Slider wird in einem **Formelfeld** (z. B. `imageSlider_Layout`) platziert. Dieses Feld sorgt für die visuelle Darstellung der Bilder und die Navigation.

### 2. Wichtige Ninox-Einstellungen

In deiner Bilder-Tabelle solltest du auf folgende Punkte achten:

- `sortId` (Zahlenfeld)
→ Dieses Feld muss für jedes Bild mit einer aufsteigenden Nummer befüllt sein (z. B. 1, 2, 3 …).
→ Es steuert die Reihenfolge, in der die Bilder im Slider angezeigt werden.
- `shareUrl` (URL-Feld)
→ Dieses Feld enthält den direkten Link zur Bilddatei – wichtig für die Anzeige im `Custom Image`-Widget.
→ Am besten wird dieser Wert automatisch beim Upload eines Bildes gesetzt.

**shareUrl automatisch hinterlegen**

Um die `shareUrl` automatisch zu befüllen, kannst du im **Bild-Feld** einen **Trigger nach Änderung** hinterlegen. So wird die URL jedes Mal aktualisiert, wenn ein neues Bild hochgeladen wird.

**Beispiel-Code für den Trigger nach Änderung:**


```javascript
shareURL := shareFile(Bild)
```

![](https://framerusercontent.com/images/Z1ncYPYpGQ7ARLeLsiDWjtVE.png)

### 3. Hilfsfeld erstellen

Lege auf der Tabelle, in der du den Image-Slider darstellen möchtest, ein **Textfeld** an – z. B. `currentImage`. Dieses Feld speichert die aktuell angezeigte Bild-ID und wird über die Navigationsbuttons im Slider verändert.

<li data-preset-tag="h3">### Anwendungscode einfügen

</li>
Erstelle nun ein **Formelfeld**, z. B. `imageSlide_Layout`, und füge dort den Anwendungscode ein. Achte dabei auf folgende Anpassungen:


```javascript
let current := this;
let nextImage := number(first(Images_Slider[sortId > record(Images_Slider,number(current.currentImage)).sortId] order by sortId).Nr);
let previousImage := number(last(Images_Slider[sortId < record(Images_Slider,number(current.currentImage)).sortId] order by sortId).Nr);
let firstImage := number(first(Images_Slider order by sortId));
let lastImage := number(last(Images_Slider order by sortId));
arcCustomLayout({
        uniqueId: "fullLayout_Image-Slider_" + Nr,
        embedded: false,
        fullscreen: false,
        direction: "horizontal",
        alignX: "center",
        alignY: "center",
        width: "",
        height: "auto",
        gap: "",
        backgroundColor: "",
        paddingY: "",
        paddingX: "30px",
        blocks: [{
                width: "",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                styles: "",
                value: arcCustomButton({
                        uniqueId: "leftButton " + Nr,
                        title: "",
                        width: "",
                        height: "",
                        alignY: "",
                        alignX: "",
                        icon: arcCustomIcon({
                                name: "caret-left",
                                color: "#9ba3af",
                                iconSize: "80px"
                            }),
                        fontSize: "",
                        fontColor: "",
                        backgroundColor: "transparent",
                        borderColor: "transparent",
                        borderRadius: "",
                        actions: [{
                                recordId: Nr,
                                type: "update",
                                field: "X",
                                value: if previousImage then previousImage else lastImage end
                            }]
                    })
            }, {
                width: "auto",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: arcCustomLayout({
                        uniqueId: "Image und Description " + Nr,
                        embedded: true,
                        fullscreen: false,
                        direction: "vertical",
                        alignX: "center",
                        alignY: "center",
                        width: "",
                        height: "",
                        gap: "20px",
                        backgroundColor: "",
                        paddingY: "",
                        paddingX: "",
                        blocks: [{
                                width: "",
                                height: "auto",
                                lineHeight: "",
                                alignX: "center",
                                color: "",
                                styles: "",
                                value: arcCustomText({
                                        uniqueId: "Headline " + Nr,
                                        embedded: true,
                                        width: "",
                                        height: "",
                                        alignY: "",
                                        alignX: "center",
                                        fontSize: "20px",
                                        fontWeight: "",
                                        fontColor: "",
                                        lineHeight: "",
                                        textWrap: "",
                                        textScroll: "",
                                        textAlign: "",
                                        textDirection: "horizontal",
                                        textDecoration: {
                                            type: "",
                                            style: "",
                                            color: "",
                                            thickness: ""
                                        },
                                        value: record(Images_Slider,number(currentImage)).Bezeichnung
                                    })
                            }, {
                                width: "",
                                height: "auto",
                                lineHeight: "",
                                alignX: "center",
                                color: "",
                                value: arcCustomImage({
                                        uniqueId: "Image " + Nr,
                                        title: "",
                                        width: "400px",
                                        height: "400px",
                                        backgroundSize: "cover",
                                        backgroundColor: "",
                                        style: "",
                                        radius: "5px",
                                        borderColor: "",
                                        link: record(Images_Slider,number(currentImage)).shareURL
                                    })
                            }]
                    })
            }, {
                width: "",
                height: "100% ",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: arcCustomButton({
                        uniqueId: "leftButton " + Nr,
                        title: "",
                        width: "",
                        height: "",
                        alignY: "",
                        alignX: "",
                        icon: arcCustomIcon({
                                name: "caret-right",
                                color: "#9ba3af",
                                iconSize: "80px"
                            }),
                        fontSize: "",
                        fontColor: "",
                        backgroundColor: "transparent",
                        borderColor: "transparent",
                        borderRadius: "",
                        actions: [{
                                recordId: Nr,
                                type: "update",
                                field: "X",
                                value: if nextImage then nextImage else firstImage end
                            }]
                    })
            }]
    })
```

💡 **Tipp: **`**embedded**`**-Parameter richtig setzen**

Je nachdem, wo du den Image-Slider einsetzen möchtest, musst du den Parameter `embedded` korrekt setzen:

- `embedded: false`
→ Wenn du den Slider direkt in einem Ninox-Formularfeld (z. B. als eigenes Layout-Feld) nutzt.
→ Der Slider verhält sich wie ein eigenständiges Widget.
- `embedded: true`
→ Wenn du den Slider innerhalb eines anderen Widgets oder in ein größeres Custom Layout einbettest.
→ Der Slider passt sich dann an die umgebende Struktur an.

### 5. Tabellen- & Feldbezüge setzen

Gleich zu Beginn des Codes müssen deine Variablen korrekt auf deine **eigene Bilder-Tabelle** und die darin enthaltenen Felder verweisen.

✍️ Was musst du hier anpassen?

- `**Images_Slider**` → Ersetze diesen Namen durch den tatsächlichen Namen deiner Ninox-Tabelle mit den Bildern.
- `**sortId**` → Ersetze durch den Namen deines Sortierfelds in dieser Tabelle (z. B. `Reihenfolge`).


```javascript
let nextImage := number(first(Images_Slider[sortId > record(Images_Slider,number(current.currentImage)).sortId] order by sortId).Nr);
let previousImage := number(last(Images_Slider[sortId < record(Images_Slider,number(current.currentImage)).sortId] order by sortId).Nr);
let firstImage := number(first(Images_Slider order by sortId));
let lastImage := number(last(Images_Slider order by sortId));
```

In den `Custom Buttons` des Sliders musst du die **fieldId** des Feldes `currentImage` angeben, damit die Buttons korrekt funktionieren. Achte darauf, die `fieldId` **in beiden Buttons** zu ersetzen:

- Button `"caret-left"`
- Button `"caret-right"`


```javascript
                value: arcCustomButton({
                        uniqueId: "leftButton " + Nr,
                        title: "",
                        width: "",
                        height: "",
                        alignY: "",
                        alignX: "",
                        icon: arcCustomIcon({
                                name: "caret-left",
                                color: "#9ba3af",
                                iconSize: "80px"
                            }),
                        fontSize: "",
                        fontColor: "",
                        backgroundColor: "transparent",
                        borderColor: "transparent",
                        borderRadius: "",
                        actions: [{
                                recordId: Nr,
                                type: "update",
                                field: "X",
                                value: if previousImage then previousImage else lastImage end
                            }]
                    })
```

### 6. Finaler Schritt: Referenzen anpassen ✅

Setze in den Record-Referenzierungen den Namen deiner Bildertabelle und deines Feldes auf der Zieltabelle ein.

⚠️ Diese Anpassung ist entscheidend, damit die Navigation im Slider korrekt funktioniert.

### 🚀 Und jetzt: Loslegen!

Wenn du alle Schritte umgesetzt hast, ist dein individuell konfigurierter **Image-Slider einsatzbereit.**
Egal ob Team-Galerie, Portfolio oder Visual-Highlight – du kannst die Bilder jetzt ganz bequem durchblättern. 🏞️✨
<!-- /host -->


---

# Individuelles Design in der CalendarWeek

Source: https://www.arc-rider.com/docs/examples/individuelles-design-in-der-calendarweek


<!-- host:react -->
# Termine gestalten und bearbeiten in React

Einen Termin mit JSX-Inhalt anzeigen und seine Startzeit über ein Formular verändern.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Die Startstunde wird in Millisekunden umgerechnet. Drag & Drop bleibt deaktiviert, da die aktuellen Drag-Callbacks keine vollständigen neuen Zielzeiten liefern.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Individuelles Design in der CalendarWeek

# Individuelles Design in der CalendarWeek

![](https://framerusercontent.com/images/8GpUlcwkZdOmzYEMBkbiw4Fy2Y.png)

In diesem Beitrag zeigen wir euch Schritt für Schritt, wie ihr mithilfe von **Layouts** und ergänzenden **Widgets** eine individuell gestaltete **Card** für die `customCalendarWeek` aufbauen könnt.

💡 Ihr lernt dabei nicht nur, wie sich Widgets elegant **ineinander verschachteln** lassen, sondern erhaltet auch direkt die passenden **Beispielcodes** aus unserem Setup.

Ob als **direkte Vorlage** (Tabellennamen, Felder und IDs müsst ihr natürlich auf euer System anpassen) – oder als **Inspiration für eure eigenen Designs** im typischen arcRiderWidget-Stil: Dieser Guide hilft euch dabei, euren Kalender optisch und funktional aufs nächste Level zu bringen.

## Benötigte Widgets

- **Widget: **[*customCalendarWeek*](/documentation/custom-calendar-week)
- **Integrierte Mini Widgets: **[*Layout*](/documentation/custom-layout)*, *[*Button*](https://www.arc-rider.de/documentation/buttons)*, *[*Select*](https://www.arc-rider.de/documentation/select)*, *[*Icon*](https://www.arc-rider.de/documentation/custom-icon)*, *[*Image*](/documentation/images)* und *[*Text*](/documentation/text)*.*

## Let’s build together 🚀

Bevor wir loslegen, sorgt bitte dafür, dass eure **Ninox-Datenbank** die nötigen Tabellen und Felder enthält – entweder nutzt ihr bestehende Strukturen oder erstellt sie neu.

Für das Layout der Card in diesem Use Case verwenden wir folgende Tabellen:

<figure><table><tbody><tr><th>


</th><th>Tabellen

</th></tr><tr><td>![](https://framerusercontent.com/images/lP1viIyLdkCNeoESjqzUBAzWc.png)

</td><td>- Kunden
- Mitarbeiter</p><ul><li data-preset-tag="p"><p>Termine
- Terminteilnehmer

</li>- Custom Calendar</p><li data-preset-tag="p"><p>Status_Termine
- Typ_Termin

</li></ul></td></tr></tbody></table></figure>***Tipp:*** Für die die Dynamische Auswahl können Hilfs/Settings Tabellen erstellt werden, wo Farb- und Iconwerte hinterlegt und dann in den jeweiligen Widgets aufgerufen werden können.

So sind die Werte zentral und müssen nicht immer wieder manuell eingegeben werden, wenn man sie auch auf anderen Oberflächen in verschiedenen Widgets einsetzen möchte.

![](https://framerusercontent.com/images/eK0VYGXu2VKBnER4WlJUYOL0tM.png)

## Individuelles Design der Card

### Widgets übersichtlich integrieren

Das Layout der calenderCard und die einzelnen zu integrierenden Widgets, werden in der Tabelle *Termine *erstellt, deren Records zum Schluss im customCalendarWeek aufgerufen werden.

![](https://framerusercontent.com/images/BRqVTA1AaUt8cqAWVWANW49wc.png)

Hier erstellen wir für jede Zeile der Card ein fx-Feld mit je einem Layout und fx-Felder für Elemente, wie weitere Layouts, Select, Button. Das bietet gute Übersichtlichkeit beim Coden der Layouts, außerdem können verschiedene Designs schneller ausgetauscht/ersetzt/getestet werden.

###  Line 1

![](https://framerusercontent.com/images/44pvIfDknaVhBorSTm8eGTIrGl4.png)

**Schritt 1:** Wir beginnen mit den ausgelagerten Elementen für die erste Zeile.

#### select_status

![](https://framerusercontent.com/images/AL1lKCPYqxa2RpoLdIEnRi2cZkU.png)

*Verwendete Widgets: customSelect + customLayout*

Code:


```javascript
let current := this;
arcCustomSelect({
        uniqueId: "Status Termin" + nr,
        recordId: nr,
        field: "Y",
        embedded: true,
        width: "100%",
        height: "25px",
        alignX: "",
        fontColor: "",
        backgroundColor: text(record(Status_Termin,number(Status)).Farbcode),
        borderColor: "none",
        borderWidth: "0px",
        borderRadius: "5px",
        itemsSettings: {
            width: "100%",
            height: "auto",
            borderRadius: "5px"
        },
        clickPosition: "",
        placeholder: "",
        disabled: false,
        reset: {
            title: "reset",
            value: "",
            hide: true
        },
        currentValue: arcCustomLayout({
                uniqueId: "status-bezeichnung-current " + nr,
                embedded: true,
                direction: "horizontal",
                alignX: "left",
                alignY: "center",
                width: "100%",
                height: "auto",
                gap: "10px",
                backgroundColor: text(record(Status_Termin,number(Status)).Farbcode),
                paddingY: "1px",
                paddingX: "1px",
                styles: "border-radius: 5px;",
                scrollSettings: {
                    scrollY: false,
                    scrollX: false
                },
                blocks: [{
                        width: "100%",
                        height: "auto",
                        lineHeight: "",
                        alignX: "left",
                        color: "",
                        styles: "",
                        value: text(record(Status_Termin,number(Status)).Bezeichnung)
                    }]
            }),
        items: let id := nr;
        (select Status_Termin).[{
                title: arcCustomLayout({
                        uniqueId: "status-bezeichnung " + Nr,
                        embedded: true,
                        direction: "horizontal",
                        alignX: "left",
                        alignY: "center",
                        width: "100%",
                        height: "",
                        gap: "0px",
                        backgroundColor: Farbcode,
                        paddingY: "3px",
                        paddingX: "5px",
                        styles: "border-radius: 5px;",
                        scrollSettings: {
                            scrollY: false,
                            scrollX: false
                        },
                        blocks: [{
                                width: "100%",
                                height: "auto",
                                lineHeight: "",
                                alignX: "left",
                                color: "",
                                styles: "",
                                value: Bezeichnung
                            }]
                    }),
                active: number(id.Status) = number(Nr),
                value: number(Nr)
            }]
    })
```

#### layout_line1_left

![](https://framerusercontent.com/images/PVJ8DYdrEqoq42ocr4Z7TVR674.png)

*Verwendete Widgets: customLayout + customIcon + customText*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard line1 left" + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "center",
        alignY: "center",
        width: "100%",
        height: "100%",
        gap: "3px",
        backgroundColor: "",
        paddingY: "0px",
        paddingX: "0px",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: [{
                width: "auto",
                height: "auto",
                alignX: "center",
                color: "",
                styles: "",
                clickAction: {
                    recordId: nr,
                    type: "popup"
                },
                value: arcCustomIcon({
                        iconSet: "phosphor",
                        name: text(record(Typ_Termin,number(Typ)).iconName),
                        containerSize: "20px",
                        iconSize: "20px",
                        color: text(record(Typ_Termin,number(current.Typ)).colorDark)
                    })
            }, {
                width: "100%",
                height: "100%",
                alignX: "left",
                color: "",
                clickAction: {
                    recordId: nr,
                    type: "popup"
                },
                value: arcCustomText({
                        uniqueId: "appointment-title" + nr,
                        embedded: true,
                        fontSize: "12px",
                        fontWeight: "700",
                        fontColor: text(record(Typ_Termin,number(current.Typ)).colorDark),
                        lineHeight: "1.2",
                        textDirection: "horizontal",
                        value: text(Bezeichnung)
                    })
            }]
    })
```

**Schritt 2: **Dann werden beide Elemente in das Layout für die erste Zeile gesetzt.

#### calendarCard_line1

![](https://framerusercontent.com/images/v6TEsRutvjB6BG1c5Ow8ZCfvLI.png)

*Verwendete Widgets: customLayout*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard line1 " + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "center",
        alignY: "top",
        width: "100%",
        height: "100%",
        gap: "10px",
        backgroundColor: "",
        paddingY: "0px",
        paddingX: "0px",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: [{
                width: "fraction",
                height: "auto",
                alignX: "center",
                color: "",
                value: layout_line1_left
            }, {
                width: "35%",
                height: "auto",
                alignX: "right",
                color: "",
                value: select_status
            }]
    })
```

### Line 2

![](https://framerusercontent.com/images/yx2JRb0qA1pCBGY8bOldxpBJ9BE.png)

**Schritt 1:** Wir beginnen wieder mit dem ausgelagerten Element für die zweite Zeile.

#### button_customer

![](https://framerusercontent.com/images/BdZ0RuNR87kw7lkQHglNBX3YU4w.png)

*Verwendete Widgets: customButton + customIcon*

Code:


```javascript
let current := this;
let lilaDark := "#35339E";
let lilaMiddle := "#D2D2F7";
arcCustomButton({
        uniqueId: "Button-kunde " + nr,
        title: text(Kunde.Name),
        embedded: true,
        width: "auto",
        height: "25px",
        alignY: "",
        alignX: "",
        paddingX: "",
        paddingY: "",
        gap: "5px",
        icon: arcCustomIcon({
                name: "link",
                color: lilaDark,
                containerSize: "20px",
                borderSize: "",
                borderColor: "",
                borderRadius: "",
                iconSize: "20px"
            }),
        iconPosition: "left",
        fontSize: "12px",
        fontColor: lilaDark,
        backgroundColor: lilaMiddle,
        borderColor: lilaMiddle,
        borderRadius: "5px",
        showBadge: false,
    })
```

**Schritt 2:** Dann wird das Element in das Layout in die zweite Zeile eingesetzt.

#### calendarCard_line2

![](https://framerusercontent.com/images/Y3WqsaZ1F91rdQrGG5rQi1P3Q.png)

*Verwendete Widgets: customLayout + customText*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard line2 " + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "center",
        alignY: "top",
        width: "100%",
        height: "100%",
        gap: "10px",
        backgroundColor: "",
        paddingY: "",
        paddingX: "",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: [{
                width: "50%",
                height: "auto",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                value: arcCustomText({
                        uniqueId: "appointment-time" + nr,
                        embedded: true,
                        fontSize: "15px",
                        fontWeight: "500",
                        fontColor: text(record(Typ_Termin,number(current.Typ)).colorDark),
                        lineHeight: "1.2",
                        textDirection: "",
                        value: text(Von) + " - " + text(Bis) + " Uhr"
                    })
            }, {
                width: "50%",
                height: "auto",
                lineHeight: "",
                alignX: "right",
                color: "",
                value: if Kunde != null then button_customer end,
                clickAction: {
                    type: "popup",
                    recordId: current.Kunde.Nr
                }
            }]
    })
```

### Line 3

![](https://framerusercontent.com/images/O4s594gvSjPVo8E0fIqyLh6fb8.png)

**Schritt 1:** Die dritte Zeile ist in zwei Layouts aufgeteilt, außerdem brauchen wir ein fx-Feld für die Berechnung der auf 3 Teilnehmer begrenzte Anzeige.

#### paginatedList_teilnehmer

Code:


```javascript
let maxEntries := 3;
let currentPage := 1;
let list := Terminteilnehmer;
let paginatedList := unique(record(Terminteilnehmer,0).Mitarbeiter)[!= 0];
for listItem in slice(list.Nr, maxEntries * (currentPage - 1), maxEntries * currentPage) do
    paginatedList := unique(paginatedList, record(Terminteilnehmer,listItem).Mitarbeiter)
end;
paginatedList
```

#### layout_buttons

![](https://framerusercontent.com/images/DWYLtB9xfkSKjIkIo0V9mLkPWtw.png)

*Verwendete Widgets: customLayout + customButton + customIcon*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "layout-buttons " + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "right",
        alignY: "center",
        width: "100%",
        height: "auto",
        gap: "5px",
        backgroundColor: "",
        paddingY: "0px",
        paddingX: "0px",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: [{
                width: "auto",
                height: "auto",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                value: arcCustomButton({
                        uniqueId: "Button-paperclip " + nr,
                        title: "",
                        width: "25px",
                        height: "25px",
                        alignY: "",
                        alignX: "",
                        paddingX: "",
                        paddingY: "",
                        gap: "5px",
                        icon: arcCustomIcon({
                                name: "paperclip-fill",
                                color: text(record(Typ_Termin,number(current.Typ)).colorDark),
                                containerSize: "25px",
                                borderSize: "",
                                borderColor: "",
                                borderRadius: "",
                                iconSize: "20px"
                            }),
                        iconPosition: "left",
                        fontSize: "12px",
                        fontColor: "",
                        backgroundColor: "none",
                        borderColor: "none",
                        borderRadius: "5px",
                        showBadge: false,
                        actions: [{
                                type: "create",
                                tableId: "",
                                popup: true,
                                changeFieldValues: [{
                                        fieldId: "",
                                        value: ""
                                    }, {
                                        fieldId: "",
                                        value: ""
                                    }]
                            }]
                    })
            }, {
                width: "auto",
                height: "auto",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                value: arcCustomButton({
                        uniqueId: "Button-message " + nr,
                        title: "",
                        width: "25px",
                        height: "25px",
                        alignY: "",
                        alignX: "",
                        paddingX: "",
                        paddingY: "",
                        gap: "5px",
                        icon: arcCustomIcon({
                                name: "chat-circle-dots-fill",
                                color: text(record(Typ_Termin,number(current.Typ)).colorDark),
                                containerSize: "25px",
                                borderSize: "",
                                borderColor: "",
                                borderRadius: "",
                                iconSize: "20px"
                            }),
                        iconPosition: "left",
                        fontSize: "12px",
                        fontColor: "",
                        backgroundColor: "none",
                        borderColor: "none",
                        borderRadius: "5px",
                        showBadge: false,
                        actions: [{
                                type: "",
                                tableId: "",
                                popup: true,
                                changeFieldValues: [{
                                        fieldId: "",
                                        value: ""
                                    }, {
                                        fieldId: "",
                                        value: ""
                                    }]
                            }]
                    })
            }, {
                width: "auto",
                height: "",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                value: arcCustomButton({
                        uniqueId: "Button-list " + nr,
                        title: "",
                        width: "25px",
                        height: "25px",
                        alignY: "",
                        alignX: "",
                        paddingX: "",
                        paddingY: "",
                        gap: "5px",
                        icon: arcCustomIcon({
                                name: "list-checks-fill",
                                color: text(record(Typ_Termin,number(current.Typ)).colorDark),
                                containerSize: "25px",
                                borderSize: "",
                                borderColor: "",
                                borderRadius: "",
                                iconSize: "20px"
                            }),
                        iconPosition: "left",
                        fontSize: "12px",
                        fontColor: "",
                        backgroundColor: "none",
                        borderColor: "none",
                        borderRadius: "5px",
                        showBadge: false,
                        actions: [{
                                type: "",
                                tableId: "",
                                popup: true,
                                changeFieldValues: [{
                                        fieldId: "",
                                        value: ""
                                    }, {
                                        fieldId: "",
                                        value: ""
                                    }]
                            }]
                    })
            }]
    })
```

#### layout_teilnehmer

![](https://framerusercontent.com/images/uC5bZCbfPqD1bXCXINIPqdHsI.png)

*Verwendete Widgets: customLayout + customImage*

Code:


```javascript
let current := this;
let colorDark := text(record(Typ_Termin,number(current.Typ)).colorDark);
let colorLight := text(record(Typ_Termin,number(current.Typ)).color);
arcCustomLayout({
        uniqueId: "layout-teilnehmer " + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "left",
        alignY: "center",
        width: "100%",
        height: "",
        gap: "0px",
        backgroundColor: "",
        paddingY: "0px",
        paddingX: "0px",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: let imageList := paginatedList_teilnehmer.[{
                    width: "auto",
                    height: "auto",
                    lineHeight: "",
                    alignX: "left",
                    color: "",
                    styles: "margin-right: -10px; border: 2px solid; border-radius: 50px; border-color: " +
                    colorLight +
                    ";",
                    value: arcCustomImage({
                            uniqueId: "Mitarbeier-image" + Nr,
                            title: "Logo",
                            width: "30px",
                            height: "30px",
                            backgroundSize: "cover",
                            class: "",
                            style: "",
                            radius: "50px",
                            borderColor: "",
                            link: shareURL
                        }),
                    clickAction: {
                        type: "popup",
                        recordId: Nr
                    }
                }];
        let plusBubble := [if cnt(Terminteilnehmer) > 3 then
                    {
                        width: "30px",
                        height: "30px",
                        lineHeight: "",
                        alignX: "center",
                        color: colorDark,
                        styles: "margin-left: 20px; border: 1px solid; border-radius: 50px; border-color: " +
                        colorDark +
                        "; font-size: 12px;",
                        value: "+" + if cnt(Terminteilnehmer) > 3 then
                            text(cnt(Terminteilnehmer) - 3)
                        end
                    }
                end];
        array(imageList, plusBubble)
    })
```

**Schritt 2:** Als nächstes werden beide customLayouts in das Layout der dritten Zeile eingesetzt.

#### calendarCard_line3

![](https://framerusercontent.com/images/grCqFlAt3BK6jGFhfciridlacU.png)

*Verwendete Widgets: customLayout*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard Line3 " + nr,
        embedded: true,
        direction: "horizontal",
        alignX: "center",
        alignY: "center",
        width: "",
        height: "auto",
        gap: "10px",
        backgroundColor: "",
        paddingY: "",
        paddingX: "",
        styles: "",
        scrollSettings: {
            scrollY: false,
            scrollX: false
        },
        blocks: [{
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "left",
                color: "",
                styles: "",
                value: layout_teilnehmer
            }, {
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "right",
                color: "",
                value: layout_buttons
            }]
    })
```

#### Card Design zusammenfügen

**Abschließend **können die Zeilen im letzten Layout der calendarCard zusammengefügt werden. Damit die Card bei kürzeren Terminen noch vollständig angeschaut werden kann, denkt dran in den scrollSettings, scrollY: true zu setzen.

![](https://framerusercontent.com/images/RgWIpNKTTKCXdAjbZ10gAJuV4iI.png)

*Verwendete Widgets: customLayout*

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard " + nr,
        embedded: true,
        direction: "vertical",
        alignX: "center",
        alignY: "top",
        width: "100%",
        height: "100%",
        gap: "10px",
        backgroundColor: record(Typ_Termin,number(current.Typ)).color,
        paddingY: "8px",
        paddingX: "8px",
        styles: "border-radius: 14px;",
        scrollSettings: {
            scrollY: true,
            scrollX: false
        },
        blocks: [{
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                styles: "",
                value: calendarCard_line1
            }, {
                width: "100%",
                height: "100%",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: calendarCard_line2
            }, {
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: calendarCard_line3
            }]
    })
```

***Tipp: **Durch die Auslagerung der einzelnen Elemente, könnt ihr super schnell weitere Designs erstellen und andere Ansichten erschaffen. Zum Beispiel die Zeilen tauschen:*

![](https://framerusercontent.com/images/lc1yOCv4jLEwkW4vMezjGhX3k.png)

Code:


```javascript
let current := this;
arcCustomLayout({
        uniqueId: "calenderCard version 2" + nr,
        embedded: true,
        direction: "vertical",
        alignX: "center",
        alignY: "top",
        width: "100%",
        height: "100%",
        gap: "10px",
        backgroundColor: record(Typ_Termin,number(current.Typ)).color,
        paddingY: "8px",
        paddingX: "8px",
        styles: "border-radius: 14px;",
        scrollSettings: {
            scrollY: true,
            scrollX: false
        },
        blocks: [{
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                styles: "",
                value: calendarCard_line2
            }, {
                width: "100%",
                height: "100%",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: calendarCard_line1
            }, {
                width: "100%",
                height: "auto",
                lineHeight: "",
                alignX: "center",
                color: "",
                value: calendarCard_line3
            }]
    })
```

## Finish Design

Die fertige Card kann **Abschließend **im Widget customCalendarWeek eingesetzt werden. Das Layout unserer calendarCard wird bei den timeEntries im Parameter **customLayout** aufgerufen.


```javascript
...		timeEntries: (select Termine where forCalendarWeek = true).[{
                subtitle: "",
                title: "",
                value: "",
                customLayout: calendarCard,
                                                                ...
```

***Wichtig!*** Wenn ihr die Hintergrundfarbe und einen borderRadius im Layout der Card definiert, müsst ihr dran denken, die backgroundColor bei den styles Parameter der timeEntries auf "transparent" sowie padding auf "0px" zu stellen.


```javascript
...		styles: {
            backgroundColor: "transparent",
            padding: "0px"
                },
                                                                ...
```

### Vollständiger Anwendungscode der customCalendarWeek:


```javascript
let current := this;
arcCustomCalendarWeek({
        uniqueId: "customCalendar" + Nr,
        embedded: false,
        height: "800px",
        weekdaySettings: {
            week: week(today()),
            year: year(today())
        },
        weekStart: 1,
        timeZoneBalance: -1,
        timeSettings: {
            timeStart: time(6, 30),
            duration: time(15, 30)
        },
        currentTime: "#f95757",
        dayHighlights: [{
                date: date(2024, 10, 31),
                color: ""
            }, {
                weekday: 6,
                color: "#f9f9f9"
            }, {
                weekday: 7,
                color: "#f9f9f9"
            }],
        lang: clientLang(),
        timeSlotWidth: "372px",
        timeSlotHeight: "120px",
        styles: {
            backgroundColor: "#cccccc11"
        },
        timeEntries: (select Termine where forCalendarWeek = true).[{
                subtitle: "",
                title: "",
                value: "",
                customLayout: calendarCard,
                dateFrom: 'Datum von',
                dateTo: 'Datum bis',
                timeFrom: Von,
                timeTo: Bis,
                styles: {
                    backgroundColor: "transparent",
                    padding: "0px"
                },
                dragAction: {
                    recordId: nr,
                    dateFrom: fieldId(nr, "Datum von"),
                    timeFrom: fieldId(nr, "Von"),
                    dateTo: fieldId(nr, "Datum bis"),
                    timeTo: fieldId(nr, "Bis")
                }
            }]
    })
```

** **
<!-- /host -->


---

# Kanban speichern und Fehler behandeln

Source: https://www.arc-rider.com/docs/examples/react-kanban-persistenz


# Kanban speichern und Fehler behandeln

Dieses Beispiel verschiebt Karten zwischen zwei flachen Spalten und speichert den bestätigten Stand im Browser. Die Arc-Select-Auswahl kann einen fehlgeschlagenen Speichervorgang simulieren.

## Vollständiges Beispiel



## Datenfluss

Der Callback kopiert die aktuelle Liste, entfernt die Karte aus der Quellspalte und fügt sie am Ziel ein. Erst nach erfolgreichem Speichern wird React-State aktualisiert. Ein abgelehntes Promise lässt den Adapter die optimistische Verschiebung abbrechen.

Das Beispiel verwendet flache Spalten. Bei gruppierten Boards beziehst du zusätzlich `source_section_index` und `target_section_index` ein. Ersetze `localStorage` durch deine API; diese sollte stabile Karten-IDs statt UI-Indizes speichern.

[Kanban-Referenz](/docs/react/widgets/custom-kanban) · [State und Events](/docs/react/patterns/react-state-events).


---

# Sortierung innerhalb einer Table

Source: https://www.arc-rider.com/docs/examples/sortierung-innerhalb-einer-table


<!-- host:react -->
# Text, Zahlen und Datum sortieren in React

Drei Spalten mit unterschiedlichen Sortiertypen konfigurieren.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

`sort.type` beschreibt die Vergleichsart. Datum und Zahlen bekommen rohe Werte in `sort.value`; die sichtbare Beschriftung bleibt frei formatiert.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Sortierung innerhalb einer Table

# Sortierung innerhalb einer Table

<iframe src="https://www.youtube.com/embed/t6vpRoe8i8A?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1&loop=1&playlist=t6vpRoe8i8A" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>In diesem Gastbeitrag von Fox Concepts zeigt dir Christoph, wie du ganz einfach eine Sortierung in der Custom Table integrierst. Bestimme selbst, in welchen Spalten nach was sortiert werden kann.

## Anwendungscode


```javascript
let dash := this;
let baseId := "SortableTable_";
let rowHeight := "40px";
let itemHeight := "30px";
let sortBy := Sortierung;
let sortDesc := Absteigend;
function sortableColumnHeader(columnTitle : text,fieldName : text) do
    "Adding a button to the header cell, that writes the actual sort request to helper fields";
    arcCustomLayout({
            uniqueId: baseId + "ColumnHeader_" + columnTitle,
            embedded: true,
            fullscreen: false,
            direction: "horizontal",
            gap: "1px",
            blocks: [{
                    height: "auto",
                    alignX: "left",
                    value: columnTitle
                }, {
                    width: "20px",
                    height: "auto",
                    alignX: "right",
                    value: arcCustomButton({
                            uniqueId: baseId + "HeaderButton_" + columnTitle,
                            embedded: true,
                            icon: GIPMaterialSymbolsV2({
                                    weight: 400,
                                    filling: 1,
                                    icon: "swap_vert",
                                    color: "#3381ff"
                                }),
                            iconPosition: "center",
                            gap: "1px",
                            showBadge: false,
                            actions: [{
                                    recordId: dash.Nr,
                                    type: "update",
                                    field: "A",
                                    value: fieldName
                                }, {
                                    recordId: dash.Nr,
                                    type: "update",
                                    field: "B",
                                    value: sortBy = fieldName and not sortDesc
                                }]
                        })
                }]
        })
end;
function getSortedList(fieldName : text) do
    "Get the sorted list according sort settings";
    let list := if fieldName != null then
            (select Kontakte) order by get(this, fieldName)
        else
            select Kontakte
        end;
    if sortDesc then
        for i in range(cnt(list), 0, -1) do
            item(list, i - 1)
        end
    else
        list
    end
end;
let list := getSortedList(dash.Sortierung);
let data := {
        uniqueListId: baseId,
        tableId: tableId(first(list)),
        height: "500px",
        header: {
            showHeader: true,
            height: rowHeight
        },
        maxHeight: "800px",
        borderColor: "black",
        minHeight: "500px",
        groupedBy: "",
        popupButtonTitle: "Open",
        scrollBar: {
            showScrollBar: true,
            width: "5px",
            height: "5px",
            backgroundColor: "",
            handle: {
                height: "5px",
                borderRadius: "",
                backgroundColor: ""
            }
        },
        table: list.[{
                recordId: Nr,
                rowHeight: "40px",
                columns: [{
                        field: "Vorname",
                        title: sortableColumnHeader("Vorname", "Vorname"),
                        value: Vorname,
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "Nachname",
                        title: sortableColumnHeader("Nachname", "Nachname"),
                        value: Nachname,
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "Straße",
                        title: sortableColumnHeader("Straße", "Straße"),
                        value: 'Straße',
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "PLZ",
                        title: sortableColumnHeader("PLZ", "PLZ"),
                        value: PLZ,
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "Ort",
                        title: sortableColumnHeader("Ort", "Ort"),
                        value: Ort,
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "Telefon",
                        title: "Telefon",
                        value: Telefon,
                        width: "220px",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }, {
                        field: "E-Mail",
                        title: "E-Mail",
                        value: 'E-Mail',
                        width: "",
                        actions: [{
                                type: "popup",
                                showPopupButton: false,
                                recordId: Nr
                            }]
                    }]
            }]
    };
arcCustomTable(data)
```
<!-- /host -->


---

# Status als Buttons ausgeben

Source: https://www.arc-rider.com/docs/examples/status-als-buttons-ausgeben


<!-- host:react -->
# Status auswählen und speichern in React

Drei Statusaktionen mit Ladeanzeige und Rückmeldung verbinden.

## Vorbereitung

Installiere das [React-Paket](/docs/react/intro/setup-react). Das Beispiel ist eine vollständige Komponente für eine Browser-App und verwendet eigene Beispieldaten.

## Vollständiges Beispiel



## So funktioniert es

Das Beispiel speichert lokal. Ersetze `localStorage.setItem` durch deinen API-Aufruf und gib das gesamte Promise aus dem Callback zurück. Ändere den bestätigten Status erst nach erfolgreichem Speichern.

## In deiner Anwendung

Halte fachliche Daten in deinem State oder Store. Ersetze lokale Beispieldaten und gegebenenfalls `localStorage` durch deinen Datenzugriff. Behandle Laden, leere Daten und Speicherfehler sichtbar in der Oberfläche.

[State und Events](/docs/react/patterns/react-state-events) · [Komponentenübersicht](/docs/react/intro/react-components).
<!-- /host -->

<!-- host:ninox,vue -->
# Status als Buttons ausgeben

# Status als Buttons ausgeben

![](https://framerusercontent.com/images/Q7g9aCNTJpdFui2qnCsHayINscg.png)

Möchtest du einen Status, beispielsweise den Aufgabenstatus, auf einer Oberfläche wie einer[ Custom Table](/documentation/custom-table) oder direkt auf deinem Datensatz anzeigen? Es gibt verschiedene Möglichkeiten, dies zu erreichen. Du kannst entweder ein [Select-Feld ](/documentation/select)verwenden, um den Status auswählbar zu machen, oder eine effizientere Methode nutzen: [Buttons](/documentation/buttons), die direkt angeklickt werden können. Diese Buttons lassen sich in einem [übersichtlichen Layout](/documentation/custom-layout) anordnen. Hier ist die Vorgehensweise:

- **Status in einer separaten Hilfstabelle anlegen**</p><p>Erstelle zunächst eine Hilfstabelle, in der die verschiedenen Statuswerte in einem Textfeld definiert werden.


- **Status auf der Zieltabelle als dynamisches Feld einblenden (Ninox)**</p><p>Blende die Statuswerte in der Zieltabelle als dynamisches Feld ein, sodass sie flexibel genutzt werden können.


- **Den Anwendungscode auf deiner Oberfläche einfügen**</p><p>Füge den erforderlichen Anwendungscode in deine Oberfläche ein. Das kann beispielsweise in einer Custom Table in einer Spalte sein oder aber blank auf deinem Ninox Record.


- **Anwendungscode auf deinen Use Case anpassen: Deine eigene Statusliste auswählen**</p><p>Wähle die entsprechende Hilfstabelle, die du bei Schritt 1 angelegt hast, bei Blocks unter „select ….“ aus, um sicherzustellen, dass die richtigen Statuswerte verwendet werden.


- **Anwendungscode auf deinen Use Case anpassen: Field bei Actions mit der fieldID deines Statusfeldes austauschen**</p><p>Tausche in den Actions das Feld mit der fieldID deines Statusfeldes, dass du bei Schritt 2 angelegt hast, aus, damit die Änderungen korrekt übernommen werden.

Mit diesen Schritten kannst du eine intuitive und benutzerfreundliche Oberfläche gestalten, auf der der Status schnell und einfach angepasst werden kann.

## Anwendungscode


```javascript
arcCustomLayout({
                                uniqueId: "statusTermin " + Nr,
                                direction: "horizontal",
                                alignX: "center",
                                alignY: "center",
                                width: "100%",
                                height: "100%",
                                gap: "10px",
                                backgroundColor: "",
                                paddingY: "10px",
                                paddingX: "10px",
                                blocks: let id := Nr;
                                (select 'Status Termin').[{
                                        align: "center",
                                        styles: "",
                                        width: "fraction",
                                        clickAction: "",
                                        value: arcCustomButton({
                                                uniqueId: "Termin_Status_" + id + Nr,
                                                title: Bezeichung,
                                                width: "100%",
                                                icon: "",
                                                fontSize: "",
                                                fontColor: if id.Status = number(Nr) then
                                                    "#fff"
                                                else
                                                    "#9ba3af"
                                                end,
                                                iconColor: "",
                                                backgroundColor: if id.Status = number(Nr) then
                                                    Farbe
                                                else
                                                    "#9ba3af33"
                                                end,
                                                borderColor: if id.Status = number(Nr) then
                                                    Farbe
                                                else
                                                    "#9ba3af33"
                                                end,
                                                borderRadius: "5px",
                                                actions: [{
                                                        recordId: id,
                                                        type: "update",
                                                        field: "Q1",
                                                        value: if id.Status = number(Nr) then
                                                            null
                                                        else
                                                            number(Nr)
                                                        end
                                                    }]
                                            })
                                    }]
                            })

```
<!-- /host -->


---

# Vertriebs-Cockpit

Source: https://www.arc-rider.com/docs/examples/react-sales-app


# Vertriebs-Cockpit

Opportunities vom Erstgespräch bis zum Abschluss begleiten. Diese vollständige Demo verbindet mehrere echte Widgets mit einem gemeinsamen Datenbestand.

## Ansichten und Workflows

**Übersicht · Pipeline · Opportunities · Aktivitäten**

- Suche und Team-Filter gelten für alle Ansichten. Ein leerer Filter zeigt den echten Leerzustand der Tabelle.
- Klicke eine Zeile, Karte oder einen Kalendertermin an und bearbeite den Eintrag im Detailbereich.
- Navigiere in den Kalenderansichten wochenweise vor und zurück.
- Ändere den Status, den Fortschritt, das Team oder den Termin. Danach bleibt die Änderung beim Wechsel der Ansicht sichtbar.
- Ziehe eine Karte zwischen den Spalten. Status, Tabellenzeile, Detailbereich und Kennzahlen verwenden danach den gleichen aktualisierten Eintrag.

## Live-App und vollständiger Code

Über **Groß öffnen** steht die App mit voller Breite zur Verfügung. **Code** zeigt exakt die ausgeführte Komponente. Du kannst sie nach der [Installation](/docs/react/intro/setup-react) direkt in eine Browser-App übernehmen.



## Zusammenspiel der Widgets

Die App hält die Einträge in einem React-State. `useMemo` leitet die gefilterte Liste ab; Tabelle, Board und Kalender erhalten daraus ihre jeweilige Konfiguration. Callbacks wählen stabile IDs aus oder verändern den gemeinsamen State. Die Widgets übernehmen Darstellung und Interaktion, die Anwendung besitzt die fachlichen Daten.

## Grenzen der Demo

Die Daten sind fiktiv und bleiben im Browser-Speicher der laufenden Komponente. Es gibt keinen Server, keine Anmeldung und keine echte Speicherung. Kalendertermine werden über den Detailbereich verändert; die aktuellen Drag-Callbacks liefern noch keine vollständigen Zielzeiten. Nach einem Neuladen beginnt die App wieder mit den Ausgangsdaten.


---

# Projekt-Cockpit

Source: https://www.arc-rider.com/docs/examples/react-projects-app


# Projekt-Cockpit

Aufgaben, Fortschritt und Termine an einem Ort. Diese vollständige Demo verbindet mehrere echte Widgets mit einem gemeinsamen Datenbestand.

## Ansichten und Workflows

**Übersicht · Kanban · Aufgaben · Kalender**

- Suche und Team-Filter gelten für alle Ansichten. Ein leerer Filter zeigt den echten Leerzustand der Tabelle.
- Klicke eine Zeile, Karte oder einen Kalendertermin an und bearbeite den Eintrag im Detailbereich.
- Navigiere in den Kalenderansichten wochenweise vor und zurück.
- Ändere den Status, den Fortschritt, das Team oder den Termin. Danach bleibt die Änderung beim Wechsel der Ansicht sichtbar.
- Ziehe eine Karte zwischen den Spalten. Status, Tabellenzeile, Detailbereich und Kennzahlen verwenden danach den gleichen aktualisierten Eintrag.

## Live-App und vollständiger Code

Über **Groß öffnen** steht die App mit voller Breite zur Verfügung. **Code** zeigt exakt die ausgeführte Komponente. Du kannst sie nach der [Installation](/docs/react/intro/setup-react) direkt in eine Browser-App übernehmen.



## Zusammenspiel der Widgets

Die App hält die Einträge in einem React-State. `useMemo` leitet die gefilterte Liste ab; Tabelle, Board und Kalender erhalten daraus ihre jeweilige Konfiguration. Callbacks wählen stabile IDs aus oder verändern den gemeinsamen State. Die Widgets übernehmen Darstellung und Interaktion, die Anwendung besitzt die fachlichen Daten.

## Grenzen der Demo

Die Daten sind fiktiv und bleiben im Browser-Speicher der laufenden Komponente. Es gibt keinen Server, keine Anmeldung und keine echte Speicherung. Kalendertermine werden über den Detailbereich verändert; die aktuellen Drag-Callbacks liefern noch keine vollständigen Zielzeiten. Nach einem Neuladen beginnt die App wieder mit den Ausgangsdaten.


---

# Ressourcenplanung

Source: https://www.arc-rider.com/docs/examples/react-resources-app


# Ressourcenplanung

Teams, Einsätze und Verfügbarkeit gemeinsam planen. Diese vollständige Demo verbindet mehrere echte Widgets mit einem gemeinsamen Datenbestand.

## Ansichten und Workflows

**Übersicht · Ressourcen · Wochenplan · Einsatzliste**

- Suche und Team-Filter gelten für alle Ansichten. Ein leerer Filter zeigt den echten Leerzustand der Tabelle.
- Klicke eine Zeile, Karte oder einen Kalendertermin an und bearbeite den Eintrag im Detailbereich.
- Navigiere in den Kalenderansichten wochenweise vor und zurück.
- Ändere den Status, den Fortschritt, das Team oder den Termin. Danach bleibt die Änderung beim Wechsel der Ansicht sichtbar.
- Wähle in der Ressourcenansicht ein Team oder einen Balken aus. Weise den Einsatz im Detailbereich einem anderen Team zu und prüfe seine neue Zeile.

## Live-App und vollständiger Code

Über **Groß öffnen** steht die App mit voller Breite zur Verfügung. **Code** zeigt exakt die ausgeführte Komponente. Du kannst sie nach der [Installation](/docs/react/intro/setup-react) direkt in eine Browser-App übernehmen.



## Zusammenspiel der Widgets

Die App hält die Einträge in einem React-State. `useMemo` leitet die gefilterte Liste ab; Tabelle, Board und Kalender erhalten daraus ihre jeweilige Konfiguration. Callbacks wählen stabile IDs aus oder verändern den gemeinsamen State. Die Widgets übernehmen Darstellung und Interaktion, die Anwendung besitzt die fachlichen Daten.

## Grenzen der Demo

Die Daten sind fiktiv und bleiben im Browser-Speicher der laufenden Komponente. Es gibt keinen Server, keine Anmeldung und keine echte Speicherung. Kalendertermine werden über den Detailbereich verändert; die aktuellen Drag-Callbacks liefern noch keine vollständigen Zielzeiten. Nach einem Neuladen beginnt die App wieder mit den Ausgangsdaten.


---

# Cyber Switch

Source: https://www.arc-rider.com/docs/components/component-cyberswitch


# Cyber Switch

# Cyber Switch Komponente

![](https://framerusercontent.com/images/PaM0ADwAFOsyz6ngHL15g2UCrL0.png)

Mit `arcCustomComponentCyberSwitch` erstellst du ganz einfach einen modernen Umschalter zwischen zwei (oder mehr) Zuständen – perfekt für Filter, Views oder einfache Statuswechsel in deiner App. Die Komponente basiert auf `arcCustomLayout` und kombiniert UI-Design und Interaktion in einem vorgefertigten, reaktiven Block.

Der Cyber Switch kommt ohne komplizierte Setup-Schritte aus: Du definierst lediglich die Items, die aktiven und inaktiven Styles – und schon ist dein Schalter einsatzbereit. Dabei kannst du das Design vollständig an dein Farbschema anpassen.

**💡 Besonders hilfreich:**

- Ideal für visuelle Filter wie "Aktiv / Inaktiv", "Heute / Morgen", "Liste / Karte" etc.
- Nutzt `clickAction`, um z. B. Felder direkt zu aktualisieren.
- Jeder Button passt sich automatisch an das übergeordnete Layout an.

Im folgenden Abschnitt findest du den Anwendungscode sowie ein Beispiel zur Anwendung in Ninox.

## Gesamter Anwendungscode

Im folgenden leeren Anwendungscode findest du ein Beispiel mit zwei Items, die manuell definiert werden – inklusive individueller `clickAction` für jeden Schalter.


```javascript
arcCustomComponentCyberSwitch({
		basicSettings: {
			backgroundColor: ""
		},
		inactiveSettings: {
			color: "",
			backgroundColor: ""
		},
		activeSettings: {
			color: "",
			backgroundColor: ""
		},
		items: [{
		title: "",
		active: "",
		clickAction: {
    		recordId: Nr,
    		type: "",
    		field: fieldId(current, "),
    		value: ""
    		}
    	}, {
		title: "",
		active: "",
		clickAction: {
    		recordId: Nr,
    		type: "",
    		field: fieldId(current, "),
    		value: ""
            }
    	}]
	})
```

## Einzelne Parameter

### basicSettings Block

Der `basicSettings`-Block definiert die grundlegenden Design-Eigenschaften der gesamten Schalter-Komponente. Aktuell gibt es nur einen konfigurierbaren Parameter:

<figure><table><tbody><tr><th>Parameter

</th><th>Beschreibung

</th><th>Default-Wert

</th></tr><tr><td>`backgroundColor`

</td><td>Hintergrund der gesamten Komponente

</td><td>`#F8FAFC`

</td></tr></tbody></table></figure>
```javascript
basicSettings: {
			backgroundColor: "#F8FAFC"
		},

```

💡 **Tipp**: Nutze helle, neutrale Farben wie `#f8fafc` oder `#e5e7eb`, um den aktiven Zustand visuell stärker hervorzuheben.

### inactiveSettings Block

Mit `inactiveSettings` legst du das Design für die nicht aktive(n) Option(en) fest – also für alle Items, die **nicht** den aktuellen Status darstellen.

<figure><table><tbody><tr><th>Parameter

</th><th>Beschreibung

</th><th>Default-Wert

</th></tr><tr><td>`color`

</td><td>Textfarbe für inaktive Buttons

</td><td>`#727c90`

</td></tr><tr><td>`backgroundColor`

</td><td>Hintergrundfarbe für inaktive Buttons

</td><td>`#F8FAFC`

</td></tr></tbody></table></figure>
```javascript
inactiveSettings: {
			color: "#727c90",
			backgroundColor: "#F8FAFC"
		},
```

💡 **Tipp: **Wähle hier dezente Farben, damit der aktive Zustand deutlich hervorsticht. Beliebt ist z. B. eine Kombination aus hellgrauem Hintergrund mit leicht abgedunkelter Schriftfarbe.

### activeSettings Block

Mit `activeSettings` gestaltest du das Design für den **aktiven** Button – also für das Item, das aktuell ausgewählt ist. Dadurch wird klar ersichtlich, welcher Zustand gerade aktiv ist.

<figure><table><tbody><tr><th>Parameter

</th><th>Beschreibung

</th><th>Default-Wert

</th></tr><tr><td>`color`

</td><td>Textfarbe für aktiven Button

</td><td>`#ffffff`

</td></tr><tr><td>`backgroundColor`

</td><td>Hintergrundfarbe für aktiven Button

</td><td>`#3b82f6`

</td></tr></tbody></table></figure>
```javascript
activeSettings: {
			color: "#fff",
			backgroundColor: "#3b82f6"
		},
```

### items Block

Im `items`-Block definierst du die einzelnen Schaltflächen (Switches), die innerhalb der CyberSwitch-Komponente angezeigt werden. Jeder Eintrag repräsentiert dabei einen Button mit eigenem Titel, Aktiv-Status und einer zugehörigen Aktion.

<figure><table><tbody><tr><th>Parameter

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>`title`

</td><td>Text, der im Button angezeigt wird.

</td><td>
```javascript
title: "Menupunkt 1",
```

</td></tr><tr><td>`active`

</td><td>Bedingung, wann der Button als aktiv dargestellt wird.

</td><td>


</td></tr><tr><td>`clickAction`

</td><td>Aktion, die beim Klick auf den Button ausgeführt wird (z. B. Feld aktualisieren).

</td><td>


</td></tr></tbody></table></figure>**💡 Hinweise zur Verwendung:**

- Du kannst beliebig viele Items definieren – mindestens zwei sind sinnvoll.
- Die Items werden automatisch gleichmäßig in der Breite verteilt (`width: "fraction"`).
- Es kann immer nur **ein** Item gleichzeitig als „aktiv“ dargestellt werden. Daher sollte dein Ausdruck bei `active` sicherstellen, dass er nur für eines zutrifft.
- Der `clickAction` nutzt den gewohnten Aktionsstandard (z. B. `type: "update"`), wie du ihn aus anderen Komponenten kennst.

## Möglichkeiten, den `items`-Block aufzubauen

Der `items`-Block kann auf zwei verschiedene Arten aufgebaut werden – je nach Anwendungsfall:

### 1. Dynamischer Aufbau über Hilfstabelle (empfohlen bei vielen Einträgen)

Wenn du eine Tabelle (z. B. `Menu`) mit deinen möglichen Schaltereinträgen hast, kannst du diese dynamisch abrufen und in Buttons umwandeln.


```javascript
items: (select Menu).[{
				title: Title,
				active: number(current.helper_Menu) = number(Nr),
				clickAction: {
					recordId: current.Nr,
					type: "update",
					field: fieldId(current, "helper_Menu"),
					value: number(Nr)
				}
			}]
```

###  2. Manueller Aufbau mit statischer Definition

Alternativ kannst du die Buttons auch einzeln manuell definieren. Das bietet dir maximale Kontrolle über Reihenfolge, Texte und Aktionen – z. B. bei einfachen Umschaltern wie "Liste / Karte" oder "Heute / Morgen".


```javascript
items: [{
		title: "Allgemein",
		active: helper_Menu = "1",
		clickAction: {
    		recordId: Nr,
    		type: "update",
    		field: fieldId(current, "helper_Menu"),
    		value: 1
    		}
    	}, {
		title: "Kontaktdaten",
		active: helper_Menu = "2",
		clickAction: {
    		recordId: Nr,
    		type: "update",
    		field: fieldId(current, "helper_Menu"),
    		value: 2
            }
    	}, {
		title: "Aufträge",
		active: helper_Menu = "3",
		clickAction: {
    		recordId: Nr,
    		type: "update",
    		field: fieldId(current, "helper_Menu"),
    		value: 3
    		}
    	}]
```

## Benötigte Widgets

Der `CyberSwitch` ist eine **kostenlose Component**, die du direkt verwenden kannst – vorausgesetzt, du hast die folgenden **Widgets in deinem Team lizenziert**:

<figure><table><tbody><tr><th>Widget

</th><th>Beschreibung

</th></tr><tr><td>`arcCustomLayout`

</td><td>Grundstruktur zur Darstellung der Buttons

</td></tr><tr><td>`arcCustomText` (optional & kostenfrei)

</td><td>Nur nötig, wenn du Texte innerhalb der Switch-Items selbst gestalten willst

</td></tr></tbody></table></figure>## 🧩 Fazit

Mit dem `arcCustomComponentCyberSwitch` kannst du in wenigen Minuten ein modernes, visuell ansprechendes Umschaltelement in deine Ninox-Oberfläche integrieren – ideal für Filter, View-Switches oder interaktive Dashboards.

Dank der Kombination mit `arcCustomLayout` ist das Design flexibel anpassbar und lässt sich nahtlos in bestehende Strukturen einfügen. Ob dynamisch über Hilfstabellen oder manuell mit gezielter Steuerung: Du behältst die volle Kontrolle.


---

# Formular aus React-Bausteinen

Source: https://www.arc-rider.com/docs/components/react-form


# Formular aus React-Bausteinen

Ein Formular kombiniert Eingaben, Statusanzeige und Aktionen. Definiere einen gemeinsamen State, führe Validierung beim Bestätigen aus und zeige Fehler neben den Eingaben.

## Vollständiges Beispiel



## Wiederverwenden

Ziehe die fachlichen Felder und Speicherfunktion als Props in deine eigene Komponente. Halte die Widgets an diesen State gebunden. Das Beispiel verwendet bewusst auch native Formularelemente: arcWidgets lassen sich mit deinen vorhandenen React-Komponenten kombinieren.

Für Auswahlfelder verwende [Select](/docs/react/mini-widgets/select), für freie Eingaben [Input](/docs/react/mini-widgets/input) und für asynchrones Speichern [Button](/docs/react/mini-widgets/buttons).


---

# Full Page Classic

Source: https://www.arc-rider.com/docs/components/full-page-classic


# Full Page Classic




---

# KPI Focus

Source: https://www.arc-rider.com/docs/components/kpi-focus


# KPI Focus

# Kompakte KPI-Übersicht für Dashboards

![](https://framerusercontent.com/images/HI2EdFNTyBNJVfddUlOkVk442M.png)

Mit `arcComponentKpiFocus()` kannst du wichtige Kennzahlen übersichtlich und ansprechend direkt in deinen Ninox-Dashboards darstellen. Jede KPI-Box zeigt eine Hauptzahl mit Icon und Titel sowie eine zusätzliche Unterzeile (Subtitle) mit weiterführenden Informationen – zum Beispiel Trends, Veränderungen oder Statusmeldungen.

Die Component eignet sich ideal für:

- Dashboard-Übersichten (z. B. Aufträge, Aufgaben, Termine)
- Lager- und Bestandsmanagement
- Team- oder Projekt-KPIs
- Jede andere Art von Kennzahlen, die schnell und klar erfassbar sein sollen

💡 Besonderheiten:

- Frei konfigurierbare Anzahl von KPI-Elementen
- Individuelle Icons und Farben pro KPI
- Subtitle-Bereich für zusätzliche Werte und kurze Beschreibungen
- Ideal kombinierbar mit anderen arcComponents und Widgets für ein konsistentes Dashboard-Design

**Vorgefertigte Komponente:** Du musst dich nicht um Layout, Farben oder Icon-Design kümmern – einfach deine eigenen Daten einsetzen und direkt loslegen.

Benötigte Widgets: [KPI Bar](https://www.arc-rider.de/documentation/custom-kpi-bar), [Layout](https://www.arc-rider.de/documentation/custom-layout), [Text](https://www.arc-rider.de/documentation/text), [Icon](https://www.arc-rider.de/documentation/custom-icon) 

## Anwendungscode


```javascript
arcComponentKpiFocus({
        uniqueId: " + Nr,
        items: [{
                id: 1,
                title: "",
                iconName: "",
                value: "",
                subtitle: {
                    color: "",
                    iconName: "",
                    value: "",
                    description: ""
                }
            }, {
                id: 2,
                title: "",
                iconName: "",
                value: "",
                subtitle: {
                    color: "",
                    iconName: "",
                    value: "",
                    description: ""
                }
            }, {
                id: 3,
                title: "",
                iconName: "",
                value: "",
                subtitle: {
                    color: "",
                    iconName: "",
                    value: "",
                    description: ""
                }
            }]
    })
```

## Parameter 

### uniqueId

- Typ: `text`
- Pflichtfeld: ja

Die uniqueId ist eine eindeutige Kennung für die Komponente. Wenn du die Komponente mehrfach auf einer Seite verwendest, solltest du die ID dynamisch erzeugen, zum Beispiel mit `+ Nr`.

### items-Block

Der Block `items` enthält alle KPI-Elemente, die innerhalb der Komponente angezeigt werden sollen. Jedes Element im Array repräsentiert eine einzelne KPI-Box mit Titel, Icon, Wert und einem optionalen Subtitle-Bereich.

Mit `items` kannst du:

- beliebig viele KPIs definieren,
- jedem KPI ein eigenes Icon und eine eigene Farbe zuweisen,
- zusätzliche Informationen wie Trends oder Statusangaben über den Subtitle hinzufügen.

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Pflicht

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>`id`

</td><td>Zahl

</td><td>✅

</td><td>Eindeutige ID des KPI-Elements. Wird zur Unterscheidung der einzelnen KPIs genutzt.

</td><td>`1`

</td></tr><tr><td>`title`

</td><td>Text

</td><td>❌

</td><td>Titel, der oberhalb des Wertes angezeigt wird.

</td><td>`"Lagerbestand"`

</td></tr><tr><td>`iconName`

</td><td>Text

</td><td>✅

</td><td>Name des Icons aus der integrierten Icon-Bibliothek.

</td><td>`"buildings"`

</td></tr><tr><td>`value`

</td><td>Text

</td><td>✅

</td><td>Der Hauptwert, der in der KPI-Box angezeigt wird.

</td><td>`text(sum(lager.sum_lagerbestand))`

</td></tr><tr><td>`subtitle`

</td><td>Objekt

</td><td>❌

</td><td>Zusätzlicher Bereich unterhalb des Hauptwerts mit Detailinformationen. Siehe unten.

</td><td>Siehe `subtitle`-Struktur

</td></tr></tbody></table></figure>### subtitle-Block

Der Block `subtitle` ist optional und erlaubt es, unterhalb des Hauptwertes zusätzliche Informationen anzuzeigen. Damit kannst du z. B. Trends, Statuswerte oder Detailinformationen zu deiner KPI hervorheben.

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Pflicht

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>`color`

</td><td>Text

</td><td>❌

</td><td>Legt die Text- und Icon-Farbe für den Subtitle fest. Unterstützt Hex- oder CSS-Farben.

</td><td>`"#3b82f6"`

</td></tr><tr><td>`iconName`

</td><td>Text

</td><td>❌

</td><td>Icon für den Subtitle. Wird links neben dem Wert angezeigt. Wird aus dem aktiven Icon-Set aus dem User Cockpit gezogen.

</td><td>`"truck"`

</td></tr><tr><td>`value`

</td><td>Text

</td><td>❌

</td><td>Der zusätzliche Wert, der im Subtitle angezeigt wird.

</td><td>`cnt(lagerbuchungen[Buchungsart = 1])`

</td></tr><tr><td>`description`

</td><td>Text

</td><td>❌

</td><td>Eine kurze Beschreibung oder Erläuterung für den Wert.

</td><td>`"neue Lieferungen"`

</td></tr></tbody></table></figure>## Beispiel

![](https://framerusercontent.com/images/X6ZMPiPuINt3bM4sjgBfTJGxDQ.png)


```javascript
arcComponentKpiFocus({
        uniqueId: "KPI Focus Component " + Nr,
        items: [{
                id: 1,
                title: "Lagerbestand",
                iconName: "buildings",
                value: text(sum(lager.sum_lagerbestand)),
                subtitle: {
                    color: "#3b82f6",
                    iconName: "truck",
                    value: cnt(lagerbuchungen[Buchungsart = 1 and week('Erstellt am') = week(today())]),
                    description: "neue Lieferungen"
                }
            }, {
                id: 2,
                title: "Warenwert",
                iconName: "coins",
                value: text(sum(lager.vk_wert_buchungen)),
                subtitle: {
                    color: "green",
                    iconName: "arrow-up-bold",
                    value: text(sum(lagerbuchungen[Buchungsart = 2 and year('Erstellt am') = year(today())].vk_wert)),
                    description: " dieses Jahr"
                }
            }, {
                id: 3,
                title: "Buchungen",
                iconName: "swap",
                value: text(cnt(lagerbuchungen)),
                subtitle: {
                    color: "red",
                    iconName: "warehouse",
                    value: "+ " + cnt(lagerbuchungen[Buchungsart = 2]),
                    description: " diese Woche"
                }
            }, {
                id: 4,
                title: "Mitarbeiter",
                iconName: "users",
                value: text(cnt(mitarbeiter)),
                subtitle: {
                    color: "#3b82f6",
                    iconName: "users",
                    value: cnt(mitarbeiter['Berechtigt zur Lagerbewegung' = true]),
                    description: "Berechtigung zur Lagerbewegung"
                }
            }]
    })
```


---

# Nested Items (Table)

Source: https://www.arc-rider.com/docs/components/hierarchisch-ausklappbare-einträge


# Nested Items (Table)

# Hierarchisch Ausklappbare Einträge

## Native nested rows (empfohlen)

Ab der Next-Gen **arcCustomTable** kannst du Hierarchien **direkt im Widget** abbilden — ohne `arcComponentNestedItems` und ohne `showChildren`-DB-Updates.

**Zwei gleichwertige Top-Level-Formen:**

- **Classic:** `table: [{ columns, items: [...] }]`
- **Neu:** root-`items: [{ columns, items: [...] }]`

```javascript
arcCustomTable({
  uniqueListId: "tasks-" + Nr,
  header: { columns: [ /* widths required */ ] },
  collapsible: { enabled: true, expandColumn: 0, indentColumn: 1 },
  table: oberaufgaben.[{
    id: Nr,
    recordId: Nr,
    columns: nestedItem_row.columns,
    items: unteraufgaben.[{ id: Nr, recordId: Nr, columns: nestedItem_row.columns, items: ... }]
  }]
})
```

- **Collapse** läuft im Browser (persistiert pro `uniqueListId`).
- **Einrückung:** `collapsible.indentColumn` + automatische Tiefe — `paddingLeft`-Formelfeld optional.
- **Parent mit breiter Zelle:** `span: 3` auf der Zelle statt Width-Summen in Ninox.

Vollständige API: [Custom Table — Nested rows](/custom-table#nested-rows-items).

---

## Legacy: `arcComponentNestedItems` (deprecated)

Der folgende Abschnitt beschreibt das **ältere Ninox-Pattern** mit `arcComponentNestedItems` und flachem `table[]`. Es funktioniert weiterhin, Migration zum nativen `items[]`-Baum wird empfohlen.

In diesem Artikel zeigen wir dir, wie du das Widget arcComponentNestedItems optimal anpasst, um hierarchisch ausklappbare Elemente in deinem Projekt umzusetzen. Egal ob du verschachtelte Menüs, Kategorien oder andere Listenstrukturen benötigst – mit unseren Tipps und Tricks kannst du die Funktionalität des Widgets erweitern und es perfekt auf deine Anforderungen abstimmen.

![](https://framerusercontent.com/images/d1EdEGEHRyhtVcof3w6hZSlbLM.png)

# Vorbereitung

Überlege dir zunächst, welche Tabellen du für deine hierarchischen Einträge benötigst. Das könnten zum Beispiel Projekte mit zugehörigen Aufgaben sein. In unserem Beispiel arbeiten wir jedoch nur mit Aufgaben und deren Unteraufgaben, die beide in der Tabelle "Aufgaben" erfasst werden. Jede Aufgabe wird dabei entweder als "Oberaufgabe" oder "Unteraufgabe" kategorisiert. Um die Hierarchie optimal darzustellen, sind folgende Felder in der Tabelle erforderlich:

- **Ja/Nein-Feld:** `showChildren` – Steuert, ob die Unteraufgaben angezeigt werden sollen.
- **Formelfeld:** `paddingLeft`
Dieses Feld sorgt für den Abstand auf der linken Seite (eingerückte Unteraufgaben) der Einträge und verwendet folgende Logik:


```javascript
let parent := Oberaufgabe;
let insetCount := 10;
while parent != null do 
	insetCount := insetCount + 10;
	parent := parent.Oberaufgabe
end
;
insetCount + "px"
```

- **Formelfeld:** `Level`
Bestimmt die Hierarchieebene der Aufgabe. Die Formel dafür lautet:


```javascript
let parent := Oberaufgabe;
let levelCount := 0;
while parent != null do 
	levelCount := levelCount + 1;
	parent := parent.Oberaufgabe
end
;
levelCount
```

- **Formelfeld:** `cntUnteraufgaben`
Zählt die Anzahl der Unteraufgaben und verwendet diese Formel:


```javascript
let children := Unteraufgaben;
cnt(children)
```

- **Formelfeld:** `nestedItem_row`
Dieses Feld bereitet die Struktur für die Anzeige der hierarchischen Einträge vor.

Diese Felder dienen als Hilfsfelder und können in einem eigenen Helper-Tab untergebracht werden, da sie auf der Hauptoberfläche nicht direkt sichtbar sein müssen.

# Gestaltung der Zeilen mit `nestedItem_row`

Mit dem folgenden Code befüllst du das Formelfeld `nestedItem_row`, wodurch du die Darstellung der einzelnen Zeilen in deiner benutzerdefinierten Tabelle (`[Custom Table](/custom-table)`) steuern kannst. In diesem Beispiel werden die Zeilen übersichtlich und funktional aufgebaut: Sie enthalten ein Symbol zum Ein- und Ausklappen, die Bezeichnung der Aufgabe und ein Feld, das die Anzahl der Unteraufgaben anzeigt. Außerdem sind die Zeilen klickbar, sodass du direkt auf den jeweiligen Datensatz zugreifen kannst. Hier der Code:


```javascript
let current := this;
{
	recordId: Nr,
	rowColor: if Level = 0 then
		"#87c5f2"
	else
		if Level = 1 then
			"#c5e4f9"
		else
			if Level = 2 then "#eff7fc" end
		end
	end,
	rowHeight: "auto",
	rowPaddingY: "5px",
	rowHoverAction: {
		hoverActive: false,
		backgroundColor: "",
		fontColor: ""
	},
	groupRowColor: "",
	groupRowSettings: {
		height: "30px"
	},
	columns: [{
			field: "",
			title: "",
			width: "40px",
			height: "",
			lineHeight: "",
			alignX: "left",
			value: arcCustomIcon({
					name: if showChildren then "minus-bold" else "plus-bold" end,
					containerSize: "25px",
					borderSize: "",
					borderColor: "",
					iconSize: "",
					borderRadius: "4px",
					color: if cnt(Unteraufgaben) > 0 then
						"
					else
						"#c5cce2"
					end,
					backgroundColor: "#eee"
				}),
			color: "",
			styles: "",
			actions: if cnt(Unteraufgaben) > 0 then
				[{
						type: "update",
						recordId: current.Nr,
						field: fieldId(this, "showChildren"),
						value: if showChildren = true then null else true end
					}]
			end
		}, {
			field: "Bezeichnung",
			title: "Bezeichnung",
			paddingX: paddingLeft,
			value: Aufgabe,
			color: "",
			backgroundColor: "",
			width: "200px",
			align: "left",
			actions: [{
					type: "popup",
					showPopupButton: false,
					recordId: current.Nr
				}]
		}, {
			field: "Anzahl Aufgaben",
			title: "Anzahl Aufgaben",
			value: if cntUnteraufgaben > 0 then
				cntUnteraufgaben + " Aufgaben"
			else
				"Keine Unteraufgaben"
			end,
			color: "",
			backgroundColor: "",
			width: "",
			align: "left",
			paddingX: paddingLeft,
			paddingY: "",
			groupExpandAction: false,
			groupValue: arcCustomIcon({
					name: "caret-down"
				}),
			groupByValue: "",
			actions: [{
					type: "popup",
					showPopupButton: false,
					recordId: current.Nr
				}]
		}]
}
```

In dieser Konfiguration:

- **Icon zum Ein- und Ausklappen:** Das Icon zeigt abhängig vom `showChildren`-Status entweder ein Minus (für ausgeklappt) oder ein Plus (für eingeklappt) an. Zudem sind die Icons bei Aufgaben ohne Unteraufgaben abgeblendet.
- **Bezeichnung der Aufgabe:** Die Bezeichnung der Aufgabe wird entsprechend eingerückt, damit die Hierarchie klar erkennbar ist.
- **Anzahl der Unteraufgaben:** Ein Textfeld zeigt die Anzahl der vorhandenen Unteraufgaben oder gibt an, wenn keine vorhanden sind.

Dieser Aufbau ermöglicht eine übersichtliche und funktionale Struktur für deine hierarchischen Einträge.

### Einfügen der hierarchischen Tabelle in die Zieloberfläche

Nun kannst du auf deiner Zieloberfläche ein Formelfeld in deiner Custom Table erstellen, das die zuvor definierten Zeilen mit `nestedItem_row` wiedergibt. Der folgende Code setzt die hierarchisch ausklappbare Struktur um:


```javascript
let list := (select Aufgaben where Oberaufgabe = null);
let showLogik := true;
let nestedData := {
		uniqueId: "Verschachtelte Items Aufgaben" + Nr,
		items: list.[{
				recordId: format(number(Nr), "0000"),
				row: nestedItem_row,
				items: if showChildren = true then
					Unteraufgaben.[{
							recordId: format(number(Nr), "0000"),
							row: nestedItem_row,
							items: if showChildren = true then
								Unteraufgaben.[{
										recordId: format(number(Nr), "0000"),
										row: nestedItem_row
									}]
							end
						}]
				end
			}]
	};
let tableData := {
		uniqueListId: "Nested Example" + Nr,
		tableId: "",
		height: "700px",
		embedded: false,
		rowHoverAction: {
			hoverActive: false,
			backgroundColor: "",
			fontColor: ""
		},
		header: {
			showHeader: true,
			height: "",
			fontColor: "",
			backgroundColor: "",
			fontSize: ""
		},
		emptyTable: {
			title: "Keine Aufgaben gefunden"
		},
		scrollBar: {
			showScrollBar: false,
			height: "",
			backgroundColor: "",
			handle: {
				height: "",
				borderRadius: "",
				backgroundColor: ""
			}
		},
		table: sort(arcComponentNestedItems(nestedData).items).row,
		footer: {
			showFooter: false,
			showActionButton: true,
			actionButtonTitle: "",
			leftSideContent: "",
			rightSideContent: ""
		}
	};
arcCustomTable(tableData)
```

Damit ist deine Tabelle für hierarchisch ausklappbare Elemente einsatzbereit!


---

# Nested Layout

Source: https://www.arc-rider.com/docs/components/layout-hierarchisch-ausklappbare-einträge


# Nested Layout

# Hierarchisch Ausklappbare Einträge

In diesem Artikel zeigen wir dir, wie du das Widget arcComponentNestedLayout optimal anpasst, um hierarchisch ausklappbare Elemente in deinem Projekt umzusetzen. Egal ob du verschachtelte Menüs, Kategorien oder andere Listenstrukturen benötigst – mit unseren Tipps und Tricks kannst du die Funktionalität des Widgets erweitern und es perfekt auf deine Anforderungen abstimmen.

![](https://framerusercontent.com/images/Cd81FvuVmPX1GAfIXPM5uDUD8c.png)

# Vorbereitung

Überlege dir zunächst, welche Tabellen du für deine hierarchischen Einträge benötigst. Das könnten zum Beispiel Projekte mit zugehörigen Aufgaben sein. In unserem Beispiel arbeiten wir jedoch nur mit Aufgaben und deren Unteraufgaben, die beide in der Tabelle "Aufgaben" erfasst werden. Jede Aufgabe wird dabei entweder als "Oberaufgabe" oder "Unteraufgabe" kategorisiert. Um die Hierarchie optimal darzustellen, sind folgende Felder in der Tabelle erforderlich:

- **Ja/Nein-Feld:** `showChildren` – Steuert, ob die Unteraufgaben angezeigt werden sollen.
- **Formelfeld:** `paddingLeft`
Dieses Feld sorgt für den Abstand auf der linken Seite (eingerückte Unteraufgaben) der Einträge und verwendet folgende Logik:


```javascript
let parent := Oberaufgabe;
let insetCount := 10;
while parent != null do 
	insetCount := insetCount + 10;
	parent := parent.Oberaufgabe
end
;
insetCount + "px"
```

- **Formelfeld:** `Level`
Bestimmt die Hierarchieebene der Aufgabe. Die Formel dafür lautet:


```javascript
let parent := Oberaufgabe;
let levelCount := 0;
while parent != null do 
	levelCount := levelCount + 1;
	parent := parent.Oberaufgabe
end
;
levelCount
```

- **Formelfeld:** `cntUnteraufgaben`
Zählt die Anzahl der Unteraufgaben und verwendet diese Formel:


```javascript
let children := Unteraufgaben;
cnt(children)
```

- **Formelfeld:** `nestedItem_row`
Dieses Feld bereitet die Struktur für die Anzeige der hierarchischen Einträge vor.

Diese Felder dienen als Hilfsfelder und können in einem eigenen Helper-Tab untergebracht werden, da sie auf der Hauptoberfläche nicht direkt sichtbar sein müssen.

# Gestaltung der Zeilen mit `nested_row`

Mit dem folgenden Code befüllst du das Formelfeld `nested_row`, wodurch du die Darstellung der einzelnen Zeilen in deinem benutzerdefinierten Layout steuern kannst. In diesem Beispiel werden die Zeilen übersichtlich und funktional aufgebaut: Sie enthalten ein Symbol zum Ein- und Ausklappen, die Bezeichnung der Aufgabe und ein Feld, das die Anzahl der Unteraufgaben anzeigt. Außerdem sind die Zeilen klickbar, sodass du direkt auf den jeweiligen Datensatz zugreifen kannst. Hier der Code:


```javascript
arcCustomLayout({
		uniqueId: Nr,
		embedded: true,
		fullscreen: false,
		direction: "horizontal",
		alignX: "center",
		alignY: "center",
		width: "",
		height: "",
		gap: "5px",
		backgroundColor: "",
		paddingY: "",
		paddingX: "",
		styles: "padding-left:" + paddingLeft + ";",
		blocks: [{
				width: "40px",
				height: "auto",
				lineHeight: "",
				alignX: "left",
				value: arcCustomIcon({
						name: if showChildren then "minus-bold" else "plus-bold" end,
						containerSize: "25px",
						borderSize: "",
						borderColor: "",
						iconSize: "",
						borderRadius: "4px",
						color: if cnt(Unteraufgaben) > 0 then
							"#ffffff"
						else
							"#ffffff33"
						end,
						backgroundColor: if cnt(Unteraufgaben) > 0 then
							"#4b4d4a"
						else
							"#4b4d4a"
						end
					}),
				color: "",
				styles: "",
				clickAction: if cnt(Unteraufgaben) > 0 then
					{
						type: "update",
						recordId: Nr,
						field: "T1",
						value: if showChildren = true then null else true end
					}
				end
			}, {
				width: "",
				height: "auto",
				lineHeight: "",
				alignX: "left",
				value: Aufgabe,
				color: "",
				clickAction: {
					type: "popup",
					recordId: Nr
				}
			}]
	})
```

In dieser Konfiguration:

- **Icon zum Ein- und Ausklappen:** Das Icon zeigt abhängig vom `showChildren`-Status entweder ein Minus (für ausgeklappt) oder ein Plus (für eingeklappt) an. Zudem sind die Icons bei Aufgaben ohne Unteraufgaben abgeblendet.
- **Bezeichnung der Aufgabe:** Die Bezeichnung der Aufgabe wird entsprechend eingerückt, damit die Hierarchie klar erkennbar ist.
- **Anzahl der Unteraufgaben:** Ein Textfeld zeigt die Anzahl der vorhandenen Unteraufgaben oder gibt an, wenn keine vorhanden sind.

Dieser Aufbau ermöglicht eine übersichtliche und funktionale Struktur für deine hierarchischen Einträge.

### Einfügen des hierarchischen Layouts in die Zieloberfläche

Nun kannst du auf deiner Zieloberfläche ein Formelfeld in deinem Custom Layout erstellen, das die zuvor definierten Zeilen mit `nested_row` wiedergibt. Der folgende Code setzt die hierarchisch ausklappbare Struktur um:


```javascript
let list := (select Aufgaben);
let data := {
		uniqueId: "Verschachtelte Items",
		items: list[Oberaufgabe = null and Aufgabe != null].[{
				recordId: Nr,
				title: nested_row,
				backgroundColor: "",
				items: if showChildren = true then
					let id := Nr;
					Unteraufgaben.[{
							recordId: Nr,
							title: nested_row,
							startDate: Startdatum,
							backgroundColor: "",
							items: if showChildren = true then
								Unteraufgaben.[{
										recordId: Nr,
										backgroundColor: "",
										title: nested_row,
										items: if showChildren = true then
											Unteraufgaben.[{
													recordId: Nr,
													backgroundColor: "",
													title: nested_row
												}]
										end
									}]
							end
						}]
				end
			}]
	};
---
 Hier betten wir die arcComponentNestedLayout() nochmal in ein Layout für das bessere Handling 
---;
arcCustomLayout({
		uniqueId: "nested layout tours" + Nr,
		embedded: false,
		fullscreen: false,
		direction: "vertical",
		alignX: "center",
		alignY: "top",
		width: "",
		styles: "",
		height: "500px",
		gap: "5px",
		backgroundColor: "#e6f0fe",
		paddingY: "20px",
		paddingX: "20px",
		scrollSettings: {
			scrollY: true
		},
		blocks: [{
				width: "100%",
				height: "auto",
				lineHeight: "",
				alignX: "left",
				color: "",
				styles: "flex-direction: column;",
				value: arcComponentNestedLayout(data)
			}]
	})
```

Damit ist dein Layout für hierarchisch ausklappbare Elemente einsatzbereit!


---

# Switch Card

Source: https://www.arc-rider.com/docs/components/component-switchcard


# Switch Card

# Component: SwitchCard

![](https://framerusercontent.com/images/7rZ98bqBrLDlaOefknMiI3aD7c.png)

Die `arcComponentSwitchCard` ist eine vielseitige UI-Komponente, die dynamisch zwischen verschiedenen Inhalten umschalten kann – etwa zwischen Lagerbeständen, Kapazitäten oder anderen Visualisierungen. Sie kombiniert eine visuell ansprechende **Karte** mit einem eingebetteten **CyberSwitch**, der zwischen den definierten Ansichten wechselt.

Typischerweise besteht sie aus:

- einem **Titel** und **Untertitel** zur Einordnung des Inhalts,
- einem **interaktiven Umschalter** (`arcCustomComponentCyberSwitch`) mit beliebig vielen Einträgen,
- und einem **dynamischen Content-Bereich**, der je nach Auswahl angepasst wird.

💡 Besonders geeignet für Dashboards oder Übersichtsseiten, bei denen Nutzer:innen zwischen mehreren Kennzahlen oder Darstellungen wechseln sollen – ohne dabei die Ansicht verlassen zu müssen.

## Anwendungscode

Im folgenden Beispiel siehst du den Grundaufbau der `SwitchCard` mit zwei Umschaltoptionen – jede davon enthält eigene Logik (`active`) und Content zur Darstellung im unteren Bereich der Karte.


```javascript
arcComponentSwitchCard({
		uniqueId: "",
		title: "",
		subtitle: "",
		switchItems: [{
				id: 1,
				title: "",
				recordId: "",
				fieldId: "",
				value: "",
				active:",
				content: ""
			}, {
				id: 2,
				title: "",
				recordId: "",
				fieldId: "",
				value: "",
				active:",
				content: ""
			},]
	})
```

## Anleitungsvideo - so baust du die switchCard einfach auf

In diesem Tutorial zeigt dir Lisa, wie du die kostenlose SwitchCard-Component in Ninox einrichten kannst.

<iframe src="https://www.youtube.com/embed/sJiWCKzSuH8?iv_load_policy=3&rel=0&modestbranding=1&playsinline=1&autoplay=1&mute=1" data-thumbnail="Medium Quality" frameborder="0" allow="presentation; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>###  

### Hauptparameter

Diese Parameter werden direkt im Aufruf der `arcComponentSwitchCard` übergeben:

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>`uniqueId`

</td><td>Text

</td><td>Eindeutige ID für die Komponente (für Styling und Wiederverwendung wichtig)

</td><td>
```javascript
uniqueId: "card element Lagerkapazitäten" + Nr,
```

</td></tr><tr><td>`title`

</td><td>Text

</td><td>Überschrift der Karte

</td><td>
```javascript
title: "Lagebestände",
```

</td></tr><tr><td>`subtitle`

</td><td>Text

</td><td>Untertitel oder Zusatzinfo unter dem Titel

</td><td>
```javascript
subtitle: "Lagebestände aller Lager",
```

</td></tr><tr><td>`switchItems`

</td><td>Liste

</td><td>Liste mit den Umschaltoptionen (siehe unten für Details)

</td><td>
```javascript
switchItems: [ {…}, {…} ]
```

</td></tr></tbody></table></figure>💡 **Hinweis: **Die `title`- und `subtitle`-Werte werden optional angezeigt – wenn sie leer sind, wird der Platz automatisch freigegeben. Der `uniqueId` sollte immer vergeben werden, um Konflikte mit anderen Komponenten zu vermeiden.

### Eintrag in `switchItems`

Jedes Element in `switchItems` repräsentiert eine **Umschaltoption** (z. B. "Bestände", "Kapazitäten", "Verteilung") mit eigenem Titel, Aktivierungslogik, Aktionslogik und angezeigtem Inhalt.

 

<figure><table><tbody><tr><th>Parameter

</th><th>Typ

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>`id`

</td><td>Zahl o. Text

</td><td>Eindeutige ID für das Item (kann z. B. für dynamisches Mapping genutzt werden)

</td><td>
```javascript
id: 1,
```

</td></tr><tr><td>`title`

</td><td>Text

</td><td>Titel des Buttons im Switch (z. B. "Bestände")

</td><td>
```javascript
title: "Bestände",
```

</td></tr><tr><td>`recordId`

</td><td>ID/Ref

</td><td>ID des aktuellen Datensatzes, auf den sich die Aktion bezieht

</td><td>
```javascript
recordId: Nr,
```

</td></tr><tr><td>`fieldId`

</td><td>Funktion o. Text (ID)

</td><td>Referenz auf das Feld, das aktualisiert werden soll

</td><td>
```javascript
fieldId: fieldId(Nr, "filter_lagerkapazitaet"),
```

</td></tr><tr><td>`value`

</td><td>beliebig

</td><td>Wert, der gesetzt werden soll, wenn der Button geklickt wird

</td><td>
```javascript
value: 2,
```

</td></tr><tr><td>`active`

</td><td>bool./Expr.

</td><td>Ausdruck, wann das Item aktiv ist

</td><td>
```javascript
active: filter_lagerkapazitaet = "2",
```

</td></tr><tr><td>`content`

</td><td>Text

</td><td>Der eigentliche Inhalt, der angezeigt wird, wenn dieses Item aktiv ist

</td><td>
```javascript
content: 'arcProgressBarComponent _lager'
```

</td></tr></tbody></table></figure>**💡 Hinweis:**

- `content` kann reiner Ninox-Text, ein Funktionsaufruf oder auch ein zusammengesetztes Widget sein.
- Es wird immer der erste Eintrag mit `active: true` angezeigt.
- Falls du nur ein Item hast, wird der Switch automatisch ausgeblendet.

###  Typische Inhalte für `content`

Der `content`-Wert kann unterschiedlich aufgebaut sein – je nachdem, welches Widget oder Element du in der Karte anzeigen möchtest. Hier einige typische Beispiele:

<figure><table><tbody><tr><th>Inhaltstyp

</th><th>Beschreibung

</th><th>Beispiel

</th></tr><tr><td>Widget-Referenz

</td><td>Aufruf eines anderen Widgets (z. B. eine Fortschrittsanzeige, ein Donut-Chart, ein eigenes Layout, etc.)

</td><td>
```javascript
content: helper_donuts_lager
```

</td></tr><tr><td>Textausgabe

</td><td>Einfacher Text (z. B. als Platzhalter oder zur schnellen Anzeige)

</td><td></td></tr></tbody></table></figure>## Benötigte Widgets

Die `SwitchCard` ist eine **kostenlose Component**, die du direkt verwenden kannst – vorausgesetzt, du hast die folgenden **Widgets in deinem Team lizenziert**:

<figure><table><tbody><tr><th>Widget

</th><th>Beschreibung

</th></tr><tr><td>`arcCustomCard`

</td><td>Grundstruktur der Karte (Layout, Padding, Hintergrund)

</td></tr><tr><td>`arcCustomLayout`

</td><td>Flexible Verschachtelung von Inhalten und Layouts

</td></tr><tr><td>`arcCustomText` (kostenfrei)

</td><td>Darstellung von Titel und Untertitel

</td></tr><tr><td>`arcCustomComponentCyberSwitch` (kostenfrei)

</td><td>Umschalter zur Auswahl der Inhalte innerhalb der Karte

</td></tr></tbody></table></figure>## Fazit

Die `SwitchCard`-Komponente ist ein leistungsstarkes UI-Element, mit dem du Inhalte dynamisch, elegant und übersichtlich darstellen kannst. Ob KPIs, Diagramme oder komplexe Widgets – die Darstellung passt sich automatisch an die Auswahl im Switch an.

Dank des modularen Aufbaus mit `arcCustomCard`, `arcCustomLayout` und `arcCustomComponentCyberSwitch` bleibt die Komponente flexibel und lässt sich problemlos in bestehende Layouts und Designsysteme integrieren.

👉 Nutze sie überall dort, wo du zwischen mehreren Ansichten oder Datenbereichen innerhalb einer Oberfläche umschalten möchtest – zum Beispiel:

- in Dashboards
- bei Detailansichten mit mehreren Datenperspektiven
- oder zur visuellen Filterung von Inhalten

Let’s make data delightful. 🚀


---

# React-Dashboard als Vorlage

Source: https://www.arc-rider.com/docs/templates/react-starter


# React-Dashboard als Vorlage

Diese Vorlage zeigt ein Widget-First-Skeleton mit Sidebar, fester Kopfzeile, Kennzahlen und einem scrollbaren Inhaltsbereich. Installiere zuerst das [React-Paket](/docs/react/intro/setup-react) und verwende die folgende Komponente in deiner Browser-App.

## Vollständige Vorlage



## Layout und Scrollen

Der einzelne Host legt mit `100dvh` die Fensterhöhe fest. Arc Layout übernimmt die eigentliche Anordnung:

- Horizontal: feste Sidebar-Breite und Block-`width: 'fraction'` für den Hauptbereich.
- Vertikal: Block-`height: 'auto'` für die Kopfzeile und `height: 'fraction'` für den Rest.
- Im restlichen Block: ein Layout mit `height: '100%'` und `scrollSettings: { scrollY: true }`.
- Der Elternbereich braucht eine definierte Höhe; `fraction` gehört auf den Block, nicht als CSS-Höhe auf das darin liegende Layout.
- Auf kleinen Bildschirmen wechseln Richtung und Blockgrößen gemeinsam. `min-width:0;min-height:0;` hält begrenzte Bereiche innerhalb des Rahmens.

## Anpassen

Ersetze die Beispieldaten durch deinen State oder Daten aus deiner API. Die Navigation ist linksbündig und verwendet Arc Icon mit Phosphor-Glyphen. Der Standard-Iconloader verwendet ein externes CDN; Offline-Apps brauchen eine ausdrücklich konfigurierte lokale Icon-Lösung. Dekorative Icons dürfen die Button-Klicks nicht abfangen.

HTML bleibt für den Host und bei Bedarf semantische Grenzen sinnvoll. Die visuelle Struktur übernimmt Arc Layout. Routing, Speicherung und API-Aufrufe bleiben bei deiner App.

Für eine kompakte Kennzahlen-/Tabellenansicht steht weiterhin `examples/blueprints/blueprint-dashboard.tsx` im Paket bereit. Weitere Vorlagen und Widgetbeispiele liegen unter `examples/widgets/`.


---

# State-Bag in einem Textfeld

Source: https://www.arc-rider.com/docs/templates/tips_statefield


Hey zusammen! 👋

Ich habe kürzlich immer mehr mit sogenannten **StateFields** gearbeitet und wollte das Konzept mal teilen – vielleicht hilft es euch auch weiter.

**Das Problem:**
Für jeden Filter, Tab oder ausgewählten Datensatz braucht man normalerweise ein eigenes Ninox-Feld. Bei komplexeren UIs hat man schnell 5–10 Helper-Felder im Schema, nur für UI-Zustände.

**Die Lösung: Ein JSON-Feld als „State-Bag"**
Ein einziges Textfeld speichert ein JSON-Objekt mit beliebig vielen Keys. Navigation, Filter, ausgewählte IDs – alles in einem Feld.

---

**1. Feld und Rohdaten auslesen**

```
let stateField := fieldId(Nr, "helper_uiState");
let stateRaw := if current.helper_uiState then
    parseJSON(text(current.helper_uiState))
else
    {}
end;
```

**2. Einzelne Werte extrahieren (mit Default-Werten)**

```
let activeTab := if item(stateRaw, "activeTab") then
    text(item(stateRaw, "activeTab"))
else
    "uebersicht"
end;

let statusFilter := if item(stateRaw, "statusFilter") then
    text(item(stateRaw, "statusFilter"))
else
    "alle"
end;

let selectedRecordId := if item(stateRaw, "selectedId") then
    text(item(stateRaw, "selectedId"))
else
    ""
end;
```

**3. Werte schreiben — empfohlen: `dataBag` auf der Action**

Partielles Patchen ohne manuelles `setItem` in der Formel — der Action Performer übernimmt Read → Patch → Write:

```
{
    type: "update",
    recordId: Nr,
    fieldId: stateField,
    dataBag: {
        base: helper_uiState,
        patch: { activeTab: "details" }
    }
}
```

Ausführlich: [`data-bag-actions`](../patterns/data-bag-actions.md) — gilt für **alle Widgets mit `actions`** (Button, Layout, Table, Drawing, …).

**Alternative (manuell):** Topf lesen → `setItem` → `formatJSON` als `value`:

```
let uiData := parseJSON(
    if current.helper_uiState then
        text(current.helper_uiState)
    else
        "{}"
    end);
setItem(uiData, "activeTab", "details");
```

Dann als Action:

```
{
    type: "update",
    recordId: Nr,
    field: stateField,
    value: formatJSON(uiData)
}
```

**4. Mehrere Keys gleichzeitig setzen (z.B. Zurück-Button)**

Mit `dataBag` mehrere Keys in einem Patch:

```
dataBag: {
    base: helper_uiState,
    patch: { selectedId: "", statusFilter: "alle" }
}
```

Oder manuell:

```
let uiDataReset := parseJSON(text(current.helper_uiState));
setItem(uiDataReset, "selectedId", "");
setItem(uiDataReset, "statusFilter", "alle");
--- value: formatJSON(uiDataReset) in der Action ---;
```

---

**Genutzte Ninox-Funktionen:**
- `parseJSON()` / `formatJSON()` – JSON ↔ Objekt (Plain-JSON im Textfeld)
- `setItem(obj, "key", value)` – Key setzen
- `item(obj, "key")` – Wert auslesen

**Legacy:** Ältere Projekte nutzen manchmal `urlEncode`/`urlDecode` um JSON in Actions zu schreiben. Für neue Apps: **`dataBag` + Plain-JSON** — siehe [`data-bag-actions`](../patterns/data-bag-actions.md#legacy-urlencoded).

**Vorteile:**
- **Ein Feld statt vieler** – Filter, Tabs, ausgewählte IDs in einem Feld
- **Einfach erweiterbar** – neuer Key = kein neues Feld im Schema
- **Übersichtlich** – alle Keys an einer Stelle dokumentieren
- **Weniger Wartung** – weniger Felder im Formular

**Tipp:** Keys am besten im Code dokumentieren:

```
--- State-Keys: activeTab (uebersicht|details), statusFilter (alle|offen|erledigt), selectedId ---;
```

Viel Spaß damit! 🚀


---

# Arc & Ninox Development Rules

Source: https://www.arc-rider.com/docs/knowledge-base/development-rules


# Arc & Ninox Development Rules

Diese Datei dient als Wissensbasis für die Entwicklung von Arc Widgets in Ninox. Sie wird kontinuierlich erweitert.

## 1. Ninox Script Syntax (Strict)

Ninox verwendet eine eigene Skriptsprache, die JavaScript ähnelt, aber wichtige Unterschiede aufweist.

### Kommentare & Block-Strings
*   ❌ **VERBOTEN**: `//` oder `/* ... */` (Führt zu Syntaxfehlern in bestimmten Kontexten).
*   ✅ **ERLAUBT**: `--- Mein Kommentar ---;` (WICHTIG: Mit Semikolon `;` abschließen, wenn es als Statement steht).
*   ⚠️ **ACHTUNG**: Innerhalb von `--- ---` dürfen keine geschweiften Klammern `{ }` verwendet werden, außer zur Variablen-Interpolation.
    *   Falsch: `--- User: { name: string } ---` (Ninox versucht `name: string` als Code auszuführen).
    *   Richtig: `--- User: ( name: string ) ---` oder `--- User: [Name: String] ---`.

#### ⚠️ **KRITISCH: Keine Kommentare innerhalb von JSON-Objekten**

Kommentare sind NUR als eigenständige Statements erlaubt, NIEMALS innerhalb von JSON-Objekt-Definitionen.

```javascript
// ❌ FALSCH: Kommentar innerhalb von JSON-Objekt
blocks: [{
    --- Das ist mein Block ---;  // FEHLER!
    width: "100%",
    value: "..."
}]

// ❌ FALSCH: comment Property (keine gültige Ninox-Property)
blocks: [{
    comment: "Das ist mein Block",  // FEHLER!
    width: "100%",
    value: "..."
}]

// ✅ RICHTIG: Kommentar als eigenständiges Statement vor dem Objekt
--- Das ist mein Block ---;
let myBlock := {
    width: "100%",
    value: "..."
};
```

**Faustregel:** Kommentare mit `--- ... ---;` sind Statements und können nur dort erscheinen, wo Statements erlaubt sind - NICHT innerhalb von `{ }` Objekt-Literalen.

### Variablen & Deklaration
*   ❌ **VERBOTEN**: `const`, `let`, `var` innerhalb von Widget-Konfigurationsobjekten.
*   ✅ **ERLAUBT**: `let myVar := ...` (nur im äußeren Ninox-Skript-Scope, nicht im JSON-Objekt).
*   **Zuweisung**: Ninox nutzt `:=` für Zuweisungen im Skript-Teil.

#### Variablen-Zuweisung für Widget-Snippets

Bei der Zuweisung komplexer Widget-Konfigurationen zu Variablen, KEINE `do...end` Blöcke verwenden. Stattdessen interne `let` Statements vor die Variablen-Zuweisung setzen.

```javascript
// ❌ FALSCH: Variable mit do...end Block
let my_card := do
    let list := (select Items);
    arcCustomCard({
        uniqueId: "card-1",
        value: list.[{ ... }]
    })
end;

// ✅ RICHTIG: let Statements davor, Variable ohne do...end
let list := (select Items);
let my_card := arcCustomCard({
    uniqueId: "card-1",
    value: list.[{ ... }]
});
```

**Für wiederverwendbare Funktionen in Snippet-Dateien:**
```javascript
// Funktionen global definieren (auf Top-Level)
function myHelper(data : any) do
    arcCustomLayout({ ... })
end;

// Dann in Variablen-Definitionen verwenden
let list := (select Items);
let my_card := arcCustomCard({
    uniqueId: "card-1",
    value: myHelper({ items: list })
});
```

**Vorteile:**
- Saubere Code-Struktur
- Funktionen sind global verfügbar
- Variablen sind direkt nutzbar ohne extra Scoping

### Strings & Interpolation
*   **HTML**: HTML-Strings müssen in Triple-Dashes `---` eingeschlossen werden.
*   **Interpolation**: Variablen in HTML-Strings werden mit `{ variableName }` eingefügt.
    *   Beispiel: `value: --- <div style="color: {data.color}">Text</div> ---`

### Funktions-Scope
*   ✅ **GLOBAL**: Funktionen sollten immer auf Top-Level definiert werden.
*   ❌ **LOKAL**: Verschachtelte Funktionen (Funktion innerhalb einer Funktion) vermeiden, da Ninox diese nicht im globalen Scope findet.

#### Funktions-Reihenfolge (Top-to-Bottom)
*   **Funktionen müssen vor ihrer Verwendung definiert sein.** Ninox wertet das Script von oben nach unten aus. Ruft `navBar` `pillButton` auf, muss `pillButton` vor `navBar` stehen, sonst: "Die Funktion ist nicht definiert: pillButton(any)".
*   Neue Helper-Funktionen, die von bestehendem Code genutzt werden, immer über dem ersten Aufruf platzieren.

## 2. Widget Konfiguration

### Grundstruktur
Die Konfiguration erfolgt immer als Funktionsaufruf, der ein JSON-Objekt zurückgibt.

```javascript
arcCustomWidgetName({
    uniqueId: "unique-id-" + Nr,
    property: "value",
    blocks: [ ... ]
})
```

### Best Practices
1.  **uniqueId**: MUSS vorhanden und einzigartig sein. Oft kombiniert mit der Record-ID (`Nr`).
    *   ⚠️ **WICHTIG**: Niemals Sonderzeichen, Kommas, Punkte oder Leerzeichen in IDs verwenden
    *   Diese IDs landen in HTML-IDs (`id="..."`) und können das Layout zerstören
    *   ❌ Falsch: `uniqueId: data.id + "-time-" + timeItem.label` (wenn label "0,5 Std." enthält)
    *   ✅ Richtig: `uniqueId: data.id + "-time-" + index` oder sanitized key
    ```javascript
    // ❌ Falsch: Label mit Sonderzeichen
    for timeItem in timeDetails do
        {
            value: arcCustomLayout({
                uniqueId: "detail-" + timeItem.label  // "0,5 Std." → HTML-Fehler!
            })
        }
    end
    
    // ✅ Richtig: Index oder sanitized key verwenden
    for timeItem in timeDetails do
        let idx := index(timeDetails, timeItem);
        {
            value: arcCustomLayout({
                uniqueId: "detail-" + idx  // Saubere ID
            })
        }
    end
    ```
2.  **embedded**: Meistens `true`, wenn es Teil eines Layouts ist.
3.  **Kein JSDoc**: Ninox-Editor unterstützt kein JSDoc. Dokumentation erfolgt separat oder via `--- Text ---`.
4.  **Widget Values**: Werte immer direkt übergeben. KEIN `if/else` für leere Werte – Widgets halten intern immer empty/null. Besser: `value: selectedTab.content` statt `value: if x then x else "" end`.

#### ⚠️ **HOHE PRIORITÄT: Null- und Leer-Fallbacks – KRITISCH FÜR AI**

**Arc Widgets fangen `null` automatisch ab.** Wenn eine Bedingung nichts zurückgibt (kein `else`-Zweig), erhält das Widget `null` und rendert korrekt. Daher:

- **NIEMALS** `else "" end` für Widget-Werte – Leerstring bricht das Rendering.
- **NIEMALS** `else null end` – redundant; den `else`-Zweig komplett weglassen.
- **IMMER** `if Bedingung then widget end` – kein `else` nötig. Widgets fangen null ab.

```javascript
// ❌ FALSCH: else "" end
leftSideContent: if hasData then arcCustomButton({...}) else "" end

// ❌ FALSCH: else null end (redundant)
leftSideContent: if hasData then arcCustomButton({...}) else null end

// ✅ RICHTIG: else weglassen – Widget erhält null automatisch
leftSideContent: if hasData then arcCustomButton({...}) end
```

**In den meisten Fällen ist `else "" end` NICHT nötig** – unsere Widgets fangen `null` automatisch ab, wenn es als Wert übergeben wird. Diese Regel ist wichtig, weil sie:
- Den Code verschlankt
- Typfehler mit `any` und gemischten Typen vermeidet (z.B. „dann/sonst liefern unterschiedliche Typen“)
- Redundanz reduziert

**`else [] end` ist NIEMALS nötig** – `null` übergeben oder den `else`-Zweig weglassen; Widgets handhaben leere Arrays.

```javascript
// ❌ VERBOTEN: else "" end
leftSideContent: if hasData then arcCustomButton({...}) else "" end

// ❌ REDUNDANT: else null end (niemals nötig)
leftSideContent: if hasData then arcCustomButton({...}) else null end

// ✅ RICHTIG: else weglassen – Widgets fangen null automatisch ab
leftSideContent: if hasData then arcCustomButton({...}) end

// ❌ Unnötig: else "" end für einfache Werte
value: if data.name then data.name else "" end

// ✅ Richtig: else weglassen – Widget erhält null, wenn Bedingung falsch
value: if data.name then data.name end

// ❌ Unnötig: else [] end
participants: if mitarbeiterData then [{ value: mitarbeiterData.name }] else [] end

// ✅ Richtig: else weglassen – Widget erhält null
participants: if mitarbeiterData then [{ value: mitarbeiterData.name }] end
```

**Ausnahme**: `else` nur verwenden, wenn der Fallback semantische Bedeutung hat (z.B. ein Standard-Label, das von „leer“ abweicht).

## 3. Datenzugriff & Actions

### Queries
Ninox-Abfragen werden direkt in die Widget-Struktur integriert, oft um Arrays für `blocks` zu generieren.
*   **Select**: `(select TableName)`
*   **Relation**: `record.RelationName`
*   **Mapping**: `(select Table).[{ value: ... }]`

#### ⚠️ **WICHTIG: Performance bei Filterung**

**Grundregel**: Bei `select`-Queries immer `where` verwenden, nicht die Bracket-Syntax `[...]`.

```javascript
// ❌ Langsamer: Bracket-Syntax bei select
let list := (select Tickets)[number(Status) = 1];

// ✅ Schneller: where-Syntax bei select
let list := (select Tickets where number(Status) = 1);

// ✅ Mit konditionaler Filterung
let filterPrio := number(filter_prio);
let list := (select Tickets where if filterPrio then number(Prio) = filterPrio else true end);
```

**Ausnahme**: Bei Untertabellen/Relations funktioniert nur die Bracket-Syntax:
```javascript
// ✅ Richtig: Bracket-Syntax bei Relations (where nicht möglich)
let items := record.Positionen[Aktiv = true];

// ❌ Falsch: where bei Relations (funktioniert nicht)
let items := record.Positionen where Aktiv = true;
```

**Zusammenfassung**:
- `(select Table where ...)` → performant bei Haupttabellen
- `relation[...]` → nur bei Untertabellen/Relations (dort geht kein `where`)

#### ⚠️ Filterwerte MÜSSEN außerhalb der Query definiert werden

Filterwerte für `where`-Klauseln oder `[...]`-Filter MÜSSEN als Variable VOR der Query definiert werden. Ninox kann Feldverweise aus anderen Kontexten (Dashboard, Parent-Record etc.) innerhalb von Query-Ausdrücken nicht zuverlässig auflösen.

```javascript
--- ❌ FALSCH: Inline-Feldzugriff in der Query ---;
let list := (select Termine where Status = dashboard.filter_status);
let items := record.Positionen[Typ = parent.SelectedType];

--- ✅ RICHTIG: Filterwert vorher extrahieren ---;
let filterStatus := dashboard.filter_status;
let list := (select Termine where Status = filterStatus);

let selectedType := parent.SelectedType;
let items := record.Positionen[Typ = selectedType];
```

Dies gilt für ALLE Queries – `select ... where`, Untertabellen `[...]` und `any`/`all`-Ausdrücke.

#### Mehrfachauswahl-Felder (Dynamic Choice Fields)

Ninox Mehrfachauswahl-Felder speichern intern eine kommaseparierte Liste von IDs. Um diese dynamisch zu verarbeiten:

**1. IDs extrahieren mit `numbers()`:**
```javascript
// numbers() gibt ein Array der ausgewählten IDs zurück
let selectedIds := numbers(Niederlassung.Typ);  // z.B. [1, 3, 5]
```

**2. Record anhand ID holen mit `record()`:**
```javascript
// record(Tabelle, ID) holt den vollständigen Datensatz
let typRecord := record(Typ_Firma, number(typId));
```

**3. Auf Felder des Records zugreifen:**
```javascript
typRecord.Titel              // Text-Feld
typRecord.'Farbe Hintergrund' // Feld mit Leerzeichen → in Hochkommas
```

**Vollständiges Pattern für dynamische Badges:**
```javascript
badges: for typId in numbers(Niederlassung.Typ) do
    let typRecord := record(Typ_Firma, number(typId));
    {
        width: "auto",
        height: "auto",
        value: arcCustomBadge({
            uniqueId: Nr + "-typ-badge-" + typId,
            value: text(typRecord.Titel),
            backgroundColor: if typRecord.'Farbe Hintergrund' then 
                text(typRecord.'Farbe Hintergrund') 
            else 
                "#888888" 
            end
        })
    }
end
```

**Wichtig:**
- `numbers()` funktioniert nur bei Mehrfachauswahl-Feldern
- Bei Einfachauswahl: direkt `number(Feld)` verwenden
- `record()` benötigt den Tabellennamen als erstes Argument (nicht die Tabellen-ID)

#### JSON-Lookup-Tabellen (for...do item end Pattern)

Um eine JSON-Liste filterbar zu machen, muss sie mit `for item in [...] do item end` gewrapped werden. Nur so kann man später mit `first(list[condition])` auf die Elemente zugreifen.

```javascript
// ❌ Falsch: Direktes Array ist nicht filterbar in Ninox
let labels := [{ diff: 0, label: "Heute" }, { diff: 1, label: "Morgen" }];
first(labels[diff = 0]);  // Funktioniert nicht!

// ✅ Richtig: Mit for...do item end aktivieren
let labels := for item in [
    { diff: 0, label: "Heute" },
    { diff: 1, label: "Morgen" },
    { diff: 2, label: "Übermorgen" },
    { diff: -1, label: "Gestern" },
    { diff: -2, label: "Vorgestern" }
] do item end;

// Jetzt filterbar!
let matchedLabel := first(labels[number(myDiff) = number(item.diff)]);
if matchedLabel then text(matchedLabel.label) else "Fallback" end
```

**Pattern für relative Datums-Texte:**
```javascript
// Oben definieren
let relativeDateLabels := for item in [
    { diff: 0, label: "Heute" },
    { diff: 1, label: "Morgen" },
    { diff: 2, label: "Übermorgen" },
    { diff: -1, label: "Gestern" },
    { diff: -2, label: "Vorgestern" }
] do item end;

// Unten verwenden
let actDate := date(myRecord.Datum);
let diff := round((actDate - today()) / 86400000);  // Millisekunden → Tage
let matchedLabel := first(relativeDateLabels[number(diff) = number(item.diff)]);
title: if matchedLabel then
    text(matchedLabel.label)
else
    if diff > 1 then
        "In " + diff + " Tagen"
    else
        if diff = 1 then
            "In 1 Tag"  // Singular!
        else
            if diff = -1 then
                "Vor 1 Tag"  // Singular!
            else
                "Vor " + abs(diff) + " Tagen"
            end
        end
    end
end
```

**Wichtig - Datums-Differenz in Ninox:**
- ❌ `days()` funktioniert nur mit der appointment-Funktion
- ✅ `round((datum1 - datum2) / 86400000)` - rechnet Millisekunden in Tage um
- 86400000 = 24h × 60min × 60s × 1000ms
- `round()` rundet auf ganze Tage
- ⚠️ **Grammatik beachten**: Singular bei 1 Tag ("In 1 Tag", nicht "In 1 Tagen")

**Vorteile:**
- Zentrale Definition, leicht erweiterbar
- Sauberer Code in der Anwendung
- Beliebig viele Spezialfälle (Heute, Morgen, Übermorgen...) ohne verschachtelte if/else
- Korrekte Singular/Plural-Grammatik

#### IMMER Anzeigenamen, NIEMALS interne IDs in NinoxScript

In NinoxScript-Code (Formeln, .arc-Dateien) **IMMER** den **Anzeigenamen** (Caption) der Felder verwenden, **NIEMALS** die interne `_id`.

Das YAML-Schema zeigt Felder so:
```
Aufgabe:           ← ANZEIGENAME → im Code verwenden
  _id: A           ← INTERNE ID → NIEMALS im NinoxScript
```

- `Aufgabe: { _id: A }` → im Code `Aufgabe` verwenden, NICHT `A`
- `Fällig: { _id: B }` → im Code `'Fällig'` verwenden, NICHT `B`
- Feldnamen mit **Umlauten** (ä, ö, ü, ß) oder **Sonderzeichen** MÜSSEN in **einfache Anführungszeichen** gesetzt werden: `'Fällig'`, `'Größe'`, `'Straße'`, `'E-Mail'`
- Feldnamen ohne Sonderzeichen brauchen keine Anführungszeichen: `Aufgabe`, `Status`, `Datum`

```javascript
--- ❌ FALSCH: interne _id verwenden ---;
if A = "offen" then 10 else 0 end
let x := B + 5
(select Termine where C = "aktiv")

--- ✅ RICHTIG: Anzeigenamen verwenden ---;
if Aufgabe = "offen" then 10 else 0 end
let x := 'Fällig' + 5
(select Termine where Status = "aktiv")
```

**Ausnahme:** Seed-Daten JSON (`ninox:seed`) verwenden `_id` als Feld-Keys, da die Ninox REST API diese erwartet.

#### fieldId immer verwenden

Bei allen Widget-Actions und Select-Fields muss `fieldId()` verwendet werden, nicht nur der Feldname als String. Die `Nr` ist entscheidend für die korrekte Feld-ID.

```javascript
// ❌ Falsch: Nur Feldname als String
field: "Bearbeiter"

// ✅ Richtig: fieldId mit korrekter Record-Nr
field: fieldId(Nr, "Bearbeiter")

// ✅ Bei JSON-Konfigurationen: fieldId oben definieren wo Nr verfügbar ist
selectField: fieldId(Nr, "Bearbeiter")  // Im JSON wo Ninox-Kontext verfügbar ist
```

**Wichtig:** In verschachtelten Strukturen oder `any`-Parametern hat Ninox keinen Zugriff mehr auf `Nr`. Daher `fieldId` immer dort aufrufen, wo der Record-Kontext noch vorhanden ist.

#### arcCustomSelect / Verknüpfungsfelder – value muss number(Nr) sein

Bei dynamischen Selects und Verknüpfungsfeldern muss der `value` in items `number(Nr)` sein, nicht rohes `Nr`. Ninox erwartet numerische Werte für Record-Referenzen.

```javascript
// ❌ FALSCH: rohes Nr
items: (select Artikel).[{ title: text('Beschreibung Excel'), value: Nr }]

// ✅ RICHTIG: number(Nr)
items: (select Artikel).[{ title: text('Beschreibung Excel'), value: number(Nr) }]
```

#### fieldId – Tabellenname erforderlich

`fieldId()` für tabellenübergreifende Referenzen (z.B. in changeFieldValues) muss den **Anzeigenamen der Tabelle** verwenden, nicht die interne Tabellen-ID. `fieldId("XE", "FieldName")` funktioniert nicht.

```javascript
// ✅ RICHTIG: Tabellen-Anzeigename
fieldId: fieldId("Auftraege", "Bearbeiter")

// ❌ FALSCH: Tabellen-ID funktioniert nicht
fieldId: fieldId("A", "Bearbeiter")
```

#### if/else Typ-Konsistenz – KRITISCH

**Ninox verlangt, dass beide Zweige `then` und `else` denselben Datentyp zurückgeben.** Sonst: „Die Ausdrücke für 'dann' und 'sonst' liefern unterschiedliche Datentypen zurück“.

```javascript
// ❌ FALSCH: string vs nid – unterschiedliche Typen
title: text(if 'Beschreibung Excel' then 'Beschreibung Excel' else Nr end)

// ✅ RICHTIG: text() in beiden Zweigen – gleicher Typ
title: if 'Beschreibung Excel' then text('Beschreibung Excel') else text(Nr) end
```

**Bei Mischung von Text und Widget** (z.B. Tabellenspalten-Wert: Text ODER arcCustomSelect) müssen beide Zweige denselben Typ liefern. Für den Textfall `arcCustomText` verwenden, damit beide Widgets zurückgeben:

```javascript
// ❌ FALSCH: html(text(...)) vs widget – weiterhin string vs nid
value: if Artikel then html(text(Artikel.'Beschreibung Excel')) else arcCustomSelect({...}) end

// ✅ RICHTIG: arcCustomText vs arcCustomSelect – beide Widgets
value: if Artikel then arcCustomText({ value: text(...), fontSize: "13px" }) else arcCustomSelect({...}) end
```

#### Dashboard-Filterfelder – `current.` Prefix verwenden

Wenn Filterfelder (z.B. `filter_status_quotes`, `filter_category`) auf dem **Dashboard-Record** (dem Formular/Record, auf dem das Widget läuft) gespeichert sind, immer über `current.` in Queries und Datenlogik zugreifen. Der Dashboard-Record ist `this` / `current`; ohne Prefix kann Ninox das Feld im falschen Kontext auflösen (z.B. in einer Schleife über Tickets).

```javascript
// ❌ Falsch: filter_status_quotes ohne current – falscher Kontext in Queries
let list := list_tickets[number(Status) = number(filter_status_quotes)];

// ✅ Richtig: current.filter_status_quotes – expliziter Dashboard-Record
let list := list_tickets[number(Status) = 4 and if current.filter_status_quotes then
    number(Status) = number(current.filter_status_quotes)
else
    true
end];
```

**Faustregel:** Filterfelder auf dem Dashboard → in Queries und Filterlogik `current.filter_feldname` verwenden.

#### Dynamische IDs in Schleifen (Counter-Pattern)

Wenn du dynamische uniqueIds in Schleifen brauchst, muss die Counter-Variable einmal mit `let` definiert und dann ohne `let` überschrieben werden.

```javascript
// ❌ Falsch: let in jeder Iteration → IDs bleiben gleich
for item in items do
    let idx := idx + 1;  // Falsch! Neue Variable in jeder Iteration
    { uniqueId: "item-" + idx }
end

// ✅ Richtig: let einmal vor der Schleife, dann ohne let überschreiben
let idx := 0;
for item in items do
    idx := idx + 1;  // Richtig! Überschreibt die äußere Variable
    { uniqueId: "item-" + idx }
end
```

**Problem bei falschem Pattern:** Alle Widgets bekommen dieselbe ID → Widgets werden nicht angezeigt (besonders bei Select/Input).

#### setItem – Mutiert Objekt In-Place

**`setItem` mutiert das übergebene Objekt in-place.** Es gibt kein neues Objekt mit der Änderung zurück. Alles, was nach dem `setItem`-Aufruf kommt, sieht das mutierte Objekt. Wenn der modifizierte State an eine Action übergeben wird (z.B. `type: "update"` mit `value`), die **gleiche Variable** verwenden, die an `setItem` übergeben wurde – sie enthält nun die Änderung.

```javascript
// ❌ Falsch: rowActionDataTeil enthält ggf. nicht die Änderung (Rückgabewert von setItem)
let rowActionDataTeil := setItem(parseJSON(...), "teiluntersuchung_recordId", text(Nr));
value: formatJSON(rowActionDataTeil)  // Hat ggf. nicht die Änderung

// ✅ Bevorzugt: dataBag patch
dataBag: { base: helper_state, patch: { teiluntersuchung_recordId: text(Nr) } }

// ✅ Manuell: Geparstes Objekt in Variable, setItem mutiert es, diese Variable verwenden
let parsedStateTeil := parseJSON(text(current.helper_state));
setItem(parsedStateTeil, "teiluntersuchung_recordId", text(Nr));
value: formatJSON(parsedStateTeil)  // parsedStateTeil hat die Änderung
```

**Faustregel:** In Variable parsen → `setItem` darauf aufrufen → diese Variable für `formatJSON` / `value` nutzen.

#### Flexible Block-Breiten statt fixer Werte

Statt feste Pixel-Breiten für Widgets zu verwenden, setze den Block auf `width: "fraction"` und das Widget auf `width: "100%"`. So passt sich die Breite dynamisch an.

```javascript
// ❌ Unnötig komplex: Feste Breiten und extra Konfiguration
{
    width: "auto",
    value: arcCustomSelect({
        width: "140px"  // Fix
    })
}

// ✅ Besser: Block fraction, Widget 100%
{
    width: "fraction",
    value: arcCustomSelect({
        width: "100%"  // Füllt Block aus
    })
}
```

### Actions

#### ⚠️ **WICHTIG: Action-Typ Hierarchie**

**Grundregel**: Bei Feld-Updates IMMER widget-vorgefertigte Actions verwenden, NIEMALS customJS für Standard-Operationen.

1. **ERSTE WAHL: `update` Action** 
   - Für alle Feld-Updates verwenden
   - Ninox Trigger werden automatisch ausgelöst
   - Sauber, wartbar, performant
   
2. **ZWEITE WAHL: Ninox Trigger + Helper-Feld**
   - Für komplexe Operationen, die Ninox-Funktionen benötigen
   - Z.B. `openURL()` für Mobile-Kompatibilität
   
3. **LETZTE WAHL: `customJS`**
   - NUR für spezielle UI-Anforderungen
   - Niemals für Feld-Updates
   - Niemals für Standard-Operationen

```javascript
// ❌ FALSCH: customJS für Feld-Updates
actions: [{
    type: "customJS",
    value: "ninoxUpdate(" + Nr + ", '" + fieldId(Nr, "Status") + "', 'Aktiv'); " +
           "ninoxUpdate(" + Nr + ", '" + fieldId(Nr, "Tab") + "', 'day');"
}]

// ✅ RICHTIG: Separate update Actions
actions: [{
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "Status"),
    value: "Aktiv"
}, {
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "Tab"),
    value: "day"
}]
```

**Vorteile von `update` Actions**:
- ✅ Ninox Trigger werden automatisch ausgeführt
- ✅ Validierungen greifen
- ✅ Änderungen werden korrekt protokolliert
- ✅ Bessere Performance
- ✅ Wartbarer Code

#### Update Action Details
*   ✅ **UPDATE**: Für Datenänderungen `type: "update"` verwenden (sauberer als customJS).
    *   **recordId**: Innerhalb von Mappings/Schleifen (`select Table`) meist `Nr` (Referenz auf den aktuellen Datensatz).
    *   **field/fieldId**: Parameter für das Feld. Achtung: Manche Widgets verlangen `field`, andere `fieldId`.
        *   Wert ist oft die interne ID (z.B. `"A1"`) oder dynamisch ermittelt via `fieldId("TableName", "FieldName")` (besser, da robust gegen Umbenennung).
    ```javascript
    actions: [{
        type: "update",
        recordId: Nr, // Aktueller Datensatz in der Schleife
        field: fieldId("MyTable", "Status"), // oder "A1"
        value: "newValue"
    }]
    ```

#### ⚠️ **KRITISCH: recordId bei Actions - NIEMALS number() verwenden**

Bei `type: "popup"` oder `type: "update"` muss `recordId` immer die **rohe `Nr`** sein, NICHT `number(Nr)`.

**Grund:** Ninox benötigt die versteckte `nxid` (Tabelle + Record-Nummer), die in `Nr` enthalten ist. `number()` entfernt diese Information!

```javascript
// ❌ FALSCH: number() entfernt nxid → Record kann nicht geöffnet werden
actions: [{
    type: "popup",
    recordId: number(helper_nextOpenActivity.Nr)  // Fehler!
}]

// ✅ RICHTIG: Nr direkt verwenden
actions: [{
    type: "popup",
    recordId: helper_nextOpenActivity.Nr  // Behält nxid
}]

// ✅ RICHTIG: Bei update auch Nr direkt
actions: [{
    type: "update",
    recordId: Nr,  // Nicht number(Nr)
    field: fieldId(Nr, "Status"),
    value: "active"
}]
```

**Faustregel:** `recordId` in Actions = immer die rohe `Nr` ohne Konvertierung!

#### Multiple Actions Pattern
Widgets unterstützen Arrays von Actions, die sequenziell ausgeführt werden:

```javascript
// Navigation + Datum setzen
actions: [{
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "Datum von"),
    value: today()
}, {
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "helper_mobileNav"),
    value: "day"
}]
```

#### Bestätigungsdialog (confirm)

Jede Action kann vor der Ausführung einen Bestätigungsdialog anzeigen, indem eine `confirm`-Property hinzugefügt wird. Der Dialog wird außerhalb des Ninox-Widget-DOM gerendert und überlebt daher Hintergrund-Neuladungen des Funktionsfelds (z.B. Datenaktualisierungen durch andere User).

```javascript
// ✅ Destruktive Aktion mit Bestätigung
actions: [{
    type: "delete",
    recordId: Nr,
    confirm: {
        title: "Datensatz löschen",
        message: "Möchten Sie diesen Datensatz wirklich löschen? Diese Aktion kann nicht rückgängig gemacht werden.",
        confirmLabel: "Löschen",
        cancelLabel: "Abbrechen",
        destructive: true
    }
}]

// ✅ Nicht-destruktive Aktion mit Bestätigung
actions: [{
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "Status"),
    value: "Archiviert",
    confirm: {
        title: "Datensatz archivieren",
        message: "Dieser Datensatz wird ins Archiv verschoben.",
        confirmLabel: "Archivieren",
        destructive: false
    }
}]
```

**Properties:**

| Property | Type | Default | Beschreibung |
|----------|------|---------|--------------|
| `title` | string | — | Dialog-Titel |
| `message` | string | — | Beschreibungstext |
| `confirmLabel` | string | `"Bestätigen"` | Label des Bestätigen-Buttons (frei wählbar) |
| `cancelLabel` | string | `"Abbrechen"` | Label des Abbrechen-Buttons (frei wählbar) |
| `destructive` | boolean | `false` | Roter Confirm-Button + Warn-Icon; `false` = blaues Info-Icon |

**Verhalten:**
- Bei Bestätigung: Die Aktion wird normal ausgeführt
- Bei Abbruch: Die Aktion wird übersprungen, keine Seiteneffekte
- Funktioniert mit ALLEN Action-Typen (`update`, `delete`, `popup`, `create`, etc.)

**Limitation:** Bei `actions`-Arrays mit mehreren Einträgen `confirm` auf eine einzelne Action setzen (typischerweise die erste oder einzige destruktive Action). Jede Action im Array wird unabhängig bestätigt.

#### Verkettete Actions (`then`)

Actions können mit der `then`-Property Folge-Aktionen nach Abschluss ausführen. Nützlich, wenn z.B. nach einem Löschen der UI-State zurückgesetzt werden soll (z.B. Detail-Ansicht schließen).

```javascript
// Datensatz löschen, dann Auswahl zurücksetzen
actions: [{
    type: "delete",
    recordId: selectedItem.Nr,
    confirm: {
        title: "Datensatz löschen",
        message: "Wirklich löschen?",
        confirmLabel: "Löschen",
        cancelLabel: "Abbrechen",
        destructive: true
    },
    then: [{
        type: "update",
        recordId: Nr,
        field: mainContentStateField,
        value: formatJSON({ selectedId: "" })
    }]
}]
```

- `then` muss ein Array von Action-Objekten sein
- Wird sequenziell nach Abschluss der Haupt-Aktion ausgeführt
- Funktioniert mit `confirm` – `then` läuft nur nach Bestätigung und erfolgreicher Haupt-Aktion

#### URLs und Telefonnummern öffnen (Mobile App Kompatibilität)

⚠️ **Problem**: `window.open()` via `customJS` funktioniert im Web, aber **nicht in Ninox Mobile Apps**

✅ **Lösung**: Ninox Helper-Feld mit `openUrl()` Trigger verwenden

**Pattern**:
1. Erstelle ein Text-Feld (z.B. `trigger_openUrl`) mit folgendem Trigger:
   ```ninox
   openURL(trigger_openUrl);
   
   trigger_openUrl := null
   ```

2. Nutze `update` Action statt `customJS`:
   ```javascript
   // ❌ Falsch: Funktioniert nur im Web
   actions: [{
       type: "customJS",
       value: "window.open('tel:+49123456789')"
   }]
   
   // ✅ Richtig: Funktioniert Web + Mobile App
   actions: [{
       type: "update",
       recordId: current.Nr,
       field: fieldId(current.Nr, "trigger_openUrl"),  // Aktuell: field, später: fieldId
       value: "tel:+49123456789"  // oder "https://..." für Links
   }]
   ```

**Beispiele**:
```javascript
// Telefonnummer
actions: [{
    type: "update",
    recordId: current.Nr,
    field: fieldId(current.Nr, "trigger_openUrl"),
    value: "tel:" + phoneNumber
}]

// Google Maps
actions: [{
    type: "update",
    recordId: current.Nr,
    field: fieldId(current.Nr, "trigger_openUrl"),
    value: "https://www.google.com/maps/search/?api=1&query=" + urlEncode(address)
}]

// Externe Website
actions: [{
    type: "update",
    recordId: current.Nr,
    field: fieldId(current.Nr, "trigger_openUrl"),
    value: "https://example.com"
}]
```

> ⚠️ **Hinweis**: Aktuell muss `field` statt `fieldId` verwendet werden. Dies wird in zukünftigen Widget-Versionen vereinheitlicht.

**Vorteile**:
- ✅ Funktioniert in Web **und** Mobile App
- ✅ Zentralisierte URL-Logik (ein Trigger für alle URL-Typen)
- ✅ Keine `customJS` Security-Einschränkungen

*   **Generic Slots**: Für flexible Komponenten `actionsLeft` / `actionsRight` statt nur `actions` verwenden, wenn das Layout es erfordert.
*   *Feature Request*: Vereinheitlichung von `field` und `fieldId` Parameter über alle Widgets hinweg.

### Formatierung (format-Funktion)

Ninox bietet die `format()`-Funktion zum Formatieren von Zahlen, Datum und Zeit. Die Funktion verwendet spezielle Format-Token (ähnlich Moment.js).

**Referenz**: [Ninox format() Dokumentation](https://forum.ninox.com/t/p8yzv31/format)

#### Datumsformatierung
```javascript
// ❌ Falsch: Ungültige Format-Tokens
format(myDate, "EEEE, dd.MM.yyyy")  // Produziert "2222, Di.12.2025"

// ✅ Richtig: Korrekte Ninox Format-Tokens
format(myDate, "dddd, DD.MM.YYYY")  // "Dienstag, 01.12.2025"

// ✅ Alternative: text() für Standard-Formatierung
text(myDate)  // Nutzt System-Locale

// ✅ Wochentag extrahieren
weekdayName(weekday(myDate))  // "Dienstag"
substr(weekdayName(weekday(myDate)), 0, 2)  // "Di"
```

**Format-Tokens für Datum:**
- `dddd` - Vollständiger Wochentag (Monday, Dienstag)
- `ddd` - Abgekürzter Wochentag (Mon, Di)
- `DD` - Tag mit führender Null (01-31)
- `MM` - Monat mit führender Null (01-12)
- `YYYY` - Jahr 4-stellig (2025)
- `Do` - Tag mit Ordnungszahl (1st, 2nd, 3rd)
- `MMMM` - Vollständiger Monatsname (January, Dezember)

**Format-Tokens für Zeit:**
- `HH` - Stunden 24h-Format mit führender Null (00-23)
- `mm` - Minuten mit führender Null (00-59)
- `ss` - Sekunden mit führender Null (00-59)

#### Zahlenformatierung
```javascript
// Format: format(number, "prefix#thousands.decimals suffix#thousands_sep#decimal_sep")
format(2385.97, "#,##0.00 €#,#0.0")  // "2.385,97 €" (DE)
format(2385.97, "$#,.#0,0")          // "$2,385.97" (US)
format(12345, "0000000000")          // "0000012345" (Leading zeros)
```

## 4. Design Patterns

### Nested Layouts
Um komplexe Designs zu erreichen, werden `arcCustomLayout` Widgets tief verschachtelt.
*   Level 1: Container (Vertical)
*   Level 2: Row (Horizontal)
*   Level 3: Item (Content)

### Generic Props
Wenn Funktionen erstellt werden, sollten die Parameter generisch benannt sein, um Wiederverwendbarkeit zu sichern.

*   **Inhalt**: Meistens `value` für den anzuzeigenden Text/Inhalt (z.B. bei `arcCustomText`, `arcCustomBadge`).
    *   *Ausnahme*: `arcCustomButton` nutzt `title`.
*   **Benennung**:
    *   `title` statt `sender` (für generische Karten-Header)
*   `subtitle` statt `company`
*   `meta` statt `timestamp`
*   `action` statt `clickFunction`

## 5. Layout & Dimensionen

### Fullscreen-Konfiguration
Für Dashboard-Layouts, die ohne Ninox-UI-Elemente angezeigt werden sollen:
*   ✅ `embedded: false` (kein eingebettetes Widget)
*   ✅ `fullscreen: true`
*   ✅ `fullscreenMode: if isAdminMode() then "" else "full" end` (im Nicht-Admin-Modus wird die Ninox-UI ausgeblendet)
*   ✅ `height: "100%"` für den äußersten Container (nicht `auto`)

### Width & Height nach Orientierung
Orientierung bestimmt, welche Dimension flexibel sein sollte:
*   **Vertical (`direction: "vertical"`)**: `width: "100%"` (Container nimmt volle Breite), `height: "auto"` (passt sich Inhalt an) oder `"100%"` für Fullscreen
*   **Horizontal (`direction: "horizontal"`)**: `height: "auto"` oder feste Höhe, `width` kann `"100%"`, `"auto"`, oder `"fraction"` sein

### Scrollbare Content-Bereiche
Um Navigation/Header oben sichtbar zu halten, während nur der Content scrollt:
*   Erstelle einen Wrapper mit `height: "fraction"` (nimmt verbleibenden Platz)
*   Setze `scrollSettings: { scrollY: true, scrollX: false }`
*   Setze `alignY: "top"` für die Ausrichtung
```javascript
// Navigation (height: auto) + Content Wrapper (height: fraction + scrollY: true)
blocks: [
    { /* Header/Nav */ height: "auto" },
    { /* Scrollable Content */ height: "fraction", value: arcCustomLayout({ scrollSettings: { scrollY: true } }) }
]
```

### CSS Positioning & Layering

#### Position Sticky
Für Sticky-Header, die beim Scrollen oben kleben bleiben:
*   ✅ **Styles im Block**: `styles: "position: sticky; top: 0px; z-index: 10; background-color: #F9FAFE;"`
*   ✅ **Overflow anpassen**: Parent-Container darf NICHT `overflow: hidden` haben
    *   Verwende `overflow-x: hidden` statt `overflow: hidden` wenn nötig
*   ✅ **Hintergrund setzen**: Ohne `background-color` scheint der Content durch
*   ✅ **Z-Index**: Für Layering über anderen Elementen (z.B. `z-index: 10`)

```javascript
// ❌ Blockiert Sticky:
arcCustomLayout({
    styles: "overflow: hidden;",
    blocks: [{ styles: "position: sticky; top: 0px;" }]
})

// ✅ Funktioniert:
arcCustomLayout({
    styles: "overflow-x: hidden;",  // Nur horizontal blockieren
    blocks: [{
        styles: "position: sticky; top: 0px; z-index: 10; background-color: #F9FAFE;"
    }]
})
```

**Wichtig:** `position: sticky` funktioniert nur, wenn zwischen dem sticky Element und dem scrollbaren Container KEIN `overflow: hidden` ist.

### Widget-spezifische Props

#### arcCustomSelect
*   **recordId** & **field**: Pflichtfelder für Daten-Binding
*   **autoFocus deaktivieren**: Verhindert automatisches Tastatur-Öffnen (wichtig auf Tablets)
    ```javascript
    focusAction: {
        autoFocus: false
    }
    ```

#### arcCustomBadge
*   **Text-Farbe**: `fontColor:` (nicht `color:` oder `textColor:`)
*   **Border**: Badge hat per default einen sichtbaren Border. Für randlose Badges `borderColor` auf `transparent` oder gleiche Farbe wie `backgroundColor` setzen.
    ```javascript
    arcCustomBadge({
        value: "Text",
        fontColor: "#FFFFFF",  // ✅ Korrekt
        backgroundColor: "#3388FF",
        borderColor: "#3388FF"  // ✅ Gleiche Farbe wie Background für unsichtbaren Border
    })
    ```

#### arcCustomButton
*   **Icon-Only Buttons**: Für Buttons ohne Text nur mit Icon
    *   Verwende `title: ""` (leerer String) für reine Icon-Buttons
    *   Setze `icon` Parameter mit `arcCustomIcon`
    *   Besser als verschachtelte Layouts, da hover-Actions und button states bereits integriert sind
    ```javascript
    // ✅ Sauber: Button mit Icon, ohne Text
    arcCustomButton({
        uniqueId: "close-btn",
        title: "",  // Leer für Icon-Only
        width: "30px",
        height: "30px",
        backgroundColor: "#EBEDF5",
        borderRadius: "50%",
        icon: arcCustomIcon({
            name: "x",
            color: "#555555",
            size: "16px"
        }),
        actions: [{ type: "update", recordId: Nr, field: "...", value: null }]
    })
    
    // ❌ Unnötig komplex: Layout-Wrapper mit Icon
    arcCustomLayout({
        width: "30px",
        height: "30px",
        clickAction: { ... },
        blocks: [{
            value: arcCustomIcon({ ... })
        }]
    })
    ```
*   **Actions im Widget**: Verwende `actions` Array im Button statt `clickAction` im Block-Wrapper
    *   Nutzt Button-Features (hover, active, disabled states)
    *   Ermöglicht zukünftige `hoverActions` Konfiguration

*   **Badge-System**: Buttons unterstützen Badges für Notifications/Counter
    *   ✅ **Separate Properties**: `showBadge`, `badgeTitle`, `badgeColor`, `badgeBackground`, `badgeBorderColor`, `badgePosition`, `badgeGap`
    *   ❌ **NICHT** ein verschachteltes `badge: { ... }` Objekt verwenden
    *   `showBadge` ist ein boolean und kann konditional gesetzt werden
    ```javascript
    // ✅ Richtig: Separate Badge-Properties
    arcCustomButton({
        uniqueId: "btn-kommentare",
        title: "Kommentare",
        showBadge: if hasNewComments then true else false end,
        badgeTitle: "3",
        badgeColor: "#FFFFFF",
        badgeBackground: "#FF3B30",
        badgeBorderColor: "#FFFFFF",
        badgePosition: "",  // Standard-Position
        badgeGap: "6px",   // Abstand zwischen Inhalt und Badge
        actions: [...]
    })
    
    // ❌ Falsch: Badge als Objekt (funktioniert nicht)
    arcCustomButton({
        uniqueId: "btn-kommentare",
        title: "Kommentare",
        badge: {
            value: "3",
            backgroundColor: "#FF3B30",
            fontColor: "#FFFFFF"
        }
    })
    ```
    
    **Conditional Badge Display Pattern**:
    ```javascript
    // Pattern: Badge nur bei bestimmter Tab-ID und wenn Content vorhanden
    showBadge: if tab.id = "kommentare" and tab.hasComment then true else false end,
    badgeTitle: text(commentCount),
    badgeColor: "#FFFFFF",
    badgeBackground: "#FF3B30"
    ```

#### arcCustomIcon
*   **Eingebautes Container-Handling**: Das Icon-Widget verwaltet seinen Container selbst
    *   Nutze `containerSize` statt externe Layout-Wrapper für Icon-Größe
    *   `size` Parameter steuert Icon-Größe innerhalb des Containers
    *   Kein zusätzliches `arcCustomLayout` um Icons nötig
*   **Container-Styling**: Alle Container-Styles können direkt am Icon gesetzt werden
    *   `backgroundColor`: Hintergrundfarbe des Icon-Containers
    *   `borderRadius`: Abrundung des Containers (z.B. `"50%"` für Kreis)
    *   `borderColor`: Rahmenfarbe des Containers
    *   `borderSize`: Rahmenstärke des Containers
    ```javascript
    // ✅ Icon mit vollständigem Container-Styling
    arcCustomIcon({
        name: "user",
        color: "#818599",              // Icon-Farbe
        size: "30px",                  // Icon-Größe
        containerSize: "52px",         // Container-Größe
        backgroundColor: "#EBEDF5",    // Container-Hintergrund
        borderRadius: "50%",           // Runder Container
        borderColor: "#DDD",           // Container-Rahmen
        borderSize: "1px"              // Rahmen-Stärke
    })
    
    // ❌ Unnötig: Zusätzliches Layout für Styling
    arcCustomLayout({
        width: "52px",
        height: "52px",
        backgroundColor: "#EBEDF5",
        styles: "border-radius: 50%; border: 1px solid #DDD;",
        blocks: [{
            value: arcCustomIcon({
                name: "user",
                color: "#818599",
                size: "30px"
            })
        }]
    })
    ```
*   **Vorteil**: Ein Widget statt verschachtelter Layouts → weniger Code, bessere Performance

#### arcCustomTable – Leerzustand
*   **Leerzustand via emptyTable**: Nutze `emptyTable` settings (title, value) statt die Tabelle mit `if hasItems then table else arcCustomLayout({ ... empty state ... }) end` zu umschließen.
*   Das Table-Widget zeigt leere Listen intern an; kein extra Layout für „Keine Daten“ nötig.

#### Ninox Zeitfelder – Anzeige
*   **`text()` statt `format()` für Zeit**: Ninox kann falsche Zeiten (z.B. 00:00) anzeigen bei `format(timeField, "HH:mm")` oder Zeit-Arithmetik. Nutze `text(timeField)` für zuverlässige Anzeige.
*   **Felder**: `'Uhrzeit von'` und `'Uhrzeit bis'` für Zeitbereiche.

## 6. Code-Qualität & Best Practices

### Leserliche Variablennamen
Verwende aussagekräftige Namen für Loop-Variablen, besonders bei verschachtelten Schleifen:
```javascript
// ❌ Schlecht:
for t in types do
    for i in items do
        // Welches "i"? Welches "t"?
    end
end

// ✅ Gut:
for typeItem in types do
    for iconItem in icons do
        // Klar und verständlich
    end
end
```

### Type Coercion bei `any` Parametern

⚠️ **Problem**: Wenn Werte als `any` in Funktionsparametern übergeben werden, verlieren sie ihre Typinformation in Ninox. Dies führt zu Fehlern bei Operationen oder Funktionsaufrufen, die spezifische Typen erwarten.

✅ **Lösung**: Explizite Typ-Konvertierung mit `number()`, `date()`, `text()` etc.

#### Zahlen-Operationen
```javascript
// ❌ Falsch: Type-Loss bei any Parameter
function calculateNextDay(data : any) do
    data.currentDate + 1  // Fehler: "Ungültiger Operator: any - number"
end

// ✅ Richtig: Explizite date() Konvertierung
function calculateNextDay(data : any) do
    date(data.currentDate) + 1  // Funktioniert
end
```

#### Datum-Formatierung
```javascript
// ❌ Falsch: format() erwartet Date-Typ
format(footerData.currentDate, "DD.MM.YYYY")  // Fehler bei any-Typ

// ✅ Richtig: date() Konvertierung vor format()
format(date(footerData.currentDate), "DD.MM.YYYY")  // Funktioniert

// ✅ Auch für month(), year(), day()
month(date(footerData.currentDate))
year(date(footerData.currentDate))
```

#### Nested Object Properties
```javascript
// ❌ Falsch: Verschachtelte any-Properties ohne Konvertierung
let weekEnd := date(data.dataDates.firstWeekDay) + 6  // firstWeekDay verliert Typ

// ✅ Richtig: Beide Werte konvertieren
let firstDay := date(data.dataDates.firstWeekDay);
let weekEnd := date(firstDay) + 6;  // Explizite Konvertierung
```

**Häufige Konvertierungen**:
- `number()` - Für Zahlen und Berechnungen
- `date()` - Für Datum-Operationen
- `text()` - Für String-Operationen
- `time()` - Für Zeit-Werte

### Text-Konvertierung in Schleifen
Werte aus Ninox-Objekten sollten mit `text()` konvertiert werden, besonders in verschachtelten Strukturen:
```javascript
// ✅ Konsistente Konvertierung:
for typeItem in cardData.types do
    {
        value: arcCustomBadge({
            value: text(typeItem.value),
            fontColor: if typeItem.color then text(typeItem.color) else "#A114A8" end,
            backgroundColor: if typeItem.backgroundColor then text(typeItem.backgroundColor) else "#FDDEFF" end
        })
    }
end
```

**Grund:** In tiefen Verschachtelungen können Ninox-Werte ihren Typ verlieren. `text()` stellt sicher, dass Strings korrekt übergeben werden.

#### ⚠️ **KRITISCH: Konsistente Datentypen in if/else Zweigen**

Beide Zweige eines if/else müssen denselben Datentyp zurückgeben. Bei Vergleichen oder Kombinationen von JSON-Werten mit String-Literalen, die JSON-Werte mit `text()` wrappen.

```javascript
// ❌ FALSCH: Vergleich von any-Typ mit String
backgroundColor: if emp.backgroundColor then emp.backgroundColor else "#888888" end
// Fehler: "any" Typ verglichen mit String-Literal

// ✅ RICHTIG: JSON-Wert mit text() wrappen
backgroundColor: if emp.backgroundColor then text(emp.backgroundColor) else "#888888" end

// ❌ FALSCH: Typ-Mischung bei Farb-Properties
fontColor: if record.Color then record.Color else "#000000" end

// ✅ RICHTIG: Konsistente text() Konvertierung
fontColor: if record.Color then text(record.Color) else "#000000" end
```

**Wann `text()` verwenden:**
- Wenn ein JSON-Objekt-Property in einem if/else mit einem String-Fallback verwendet wird
- Wenn JSON-Werte mit String-Literalen verkettet werden
- Wenn JSON-Properties an Widget-Properties übergeben werden, die Strings erwarten

**Faustregel:** Wenn der else-Zweig ein String-Literal wie `"#888888"` ist, muss der if-Zweig auch einen String via `text()` zurückgeben.

## 7. Array-Handling & Dynamic Content

### Array-Funktion vs. Layout-Blocks
Ninox bietet die `array()`-Funktion zum Zusammenführen von Arrays, aber in Widget-Kontexten ist die Verwendung von verschachtelten Layouts oft sauberer und flexibler.

#### ⚠️ **WICHTIG: array() ist meist unnötig**

Blöcke können direkt nebeneinander gesetzt werden - `array()` ist nur nötig wenn tatsächlich Arrays kombiniert werden müssen.

```javascript
// ❌ Unnötig: array() mit if-else
blocks: array(
    if condition then [{ value: widget1 }] else [] end,
    for item in items do { value: widget2 } end
)

// ✅ Besser: Direkt nebeneinander, kein array(), kein else
blocks: [
    if condition then { value: widget1 } end,
    for item in items do { value: widget2 } end
]
```

**Merke:** Ninox filtert `null`-Werte automatisch aus Arrays. Daher:
- Kein `else []` nötig bei bedingten Blöcken
- Kein `array()` nötig um Blöcke zu kombinieren
- Einfach Blöcke/Schleifen kommasepariert auflisten

#### ❌ Vermeiden: Verschachtelte array() Aufrufe
```javascript
// Problematisch: Schwer zu lesen, Verschachtelungstiefe begrenzt
blocks: array(typeBadges, array(teilnehmerBadges, durationBadges))
```

#### ✅ Bevorzugt: Wrapper-Layouts mit direkten Blocks
```javascript
// Sauber: Jede Badge-Gruppe hat eigenes Layout
blocks: [
    {
        value: arcCustomLayout({
            uniqueId: "types-wrapper",
            direction: "horizontal",
            gap: "6px",
            blocks: typeBadges  // Direkt einsetzen
        })
    },
    {
        value: arcCustomLayout({
            uniqueId: "teilnehmer-wrapper",
            direction: "horizontal",
            gap: "4px",
            blocks: teilnehmerBadges  // Direkt einsetzen
        })
    },
    if durationValue then
        {
            value: arcCustomBadge({ ... })
        }
    end
]
```

**Vorteile:**
- Bessere Lesbarkeit und Wartbarkeit
- Individuelle Styling-Kontrolle pro Gruppe (Gap, Ausrichtung)
- Keine Limit-Probleme bei `array()` (Ninox erlaubt nur 2-3 verschachtelte Arrays)
- Leichteres Debugging

**Wann array() nutzen:**
- Wenn nur 2 einfache Arrays kombiniert werden müssen
- Bei flachen Strukturen ohne weitere Styling-Anforderungen
- Beispiel: `actionsLeft: array(typeBadges, teilnehmerBadges)`

#### Array-Merge (Referenzen) – 3 oder mehr Arrays

Die Ninox-Funktion `array()` akzeptiert **nur 2 Argumente**. Um 3 oder mehr Arrays zusammenzuführen, muss die Funktion mehrfach sequentiell aufgerufen werden.

```javascript
// ✅ RICHTIG: Sequentielles array() für 3+ Arrays
let listCombined := array(list1, list2);
listCombined := array(listCombined, list3);
```

**Offizielle Ninox-Dokumentation:** „If you need to merge more than 2 arrays, just execute the function as often as needed.“ ([array() Function](https://docs.ninox.com/en/script/functions-overview/functions/array))

**concat() und join() sind KEINE Alternative** – sie liefern Strings, keine Arrays. Ein Workaround wie `split(concat(ar1) + ", " + concat(ar2), ",")` wandelt alle Werte in Text um und führt zu Typverlust (Zahlen werden zu Strings; bei Werten mit Komma im Text entstehen falsche Splits). Für echte Array-Merges immer `array()` verwenden.

**Referenzen:**
- [Ninox array()](https://docs.ninox.com/en/script/functions-overview/functions/array) – offizielle Dokumentation
- [Forum: How can I add two arrays?](https://forum.ninox.com/t/x2hr89p) – concat/join liefern Strings
- [Forum: Some User Defined Array Functions](https://forum.ninox.com/t/h7hr822) – aMerge-Workaround (textbasiert, nur für String-Arrays geeignet)

**Code-Referenz im Projekt:** `projects/desktop-calendar-planning/desktop-calendar-planning.arctemplate` Zeilen 2439–2440

#### ⚠️ **KRITISCH: Multiple for-Schleifen in blocks**

Ninox erlaubt KEINE zwei for-Schleifen direkt nebeneinander in einem `blocks`-Array. Jede for-Schleife braucht ein eigenes Wrapper-Layout.

```javascript
// ❌ FEHLER: Zwei for-Schleifen direkt nebeneinander
blocks: [
    for sel in data.selects do { value: arcCustomSelect({...}) } end,
    for btn in data.buttons do { value: arcCustomButton({...}) } end
]

// ✅ RICHTIG: Jede for-Schleife in eigenem Wrapper-Layout
blocks: [{
    width: "fraction",
    value: arcCustomLayout({
        uniqueId: "selects-wrapper",
        direction: "horizontal",
        blocks: for sel in data.selects do
            { value: arcCustomSelect({...}) }
        end
    })
}, {
    width: "auto",
    value: arcCustomLayout({
        uniqueId: "buttons-wrapper",
        direction: "horizontal",
        blocks: for btn in data.buttons do
            { value: arcCustomButton({...}) }
        end
    })
}]
```

**Grund:** Ninox interpretiert zwei for-Schleifen nacheinander als Syntaxfehler. Das Wrapper-Layout kapselt jede Schleife sauber ab.

#### ⚠️ **KRITISCH: Sections mit unterschiedlichen Daten – for-Schleife, kein statisches Array**

Bei mehreren Sections (z.B. "Heute", "Morgen", "Nächste 7 Tage"), wo jede Section eigene Listen mit **section-spezifischen Daten** hat (z.B. Terminkarten mit unterschiedlichen Teilnehmern pro Karte), **muss** eine for-Schleife über die Sections verwendet werden.

```javascript
// ❌ FALSCH: Statisches Array – Daten einer Section können in andere "leaken"
blocks: [
    dashboardSection({ sectionId: "heute", appointments: sectionHeuteList }),
    dashboardSection({ sectionId: "morgen", appointments: sectionMorgenList }),
    ...
]

// ✅ RICHTIG: for-Schleife stellt pro Section eigenen Auswertungskontext sicher
blocks: for section in sections[visible = true and cnt(list) > 0] do
    {
        width: "100%",
        value: dashboardSection({
            sectionId: section.sectionId,
            appointments: for item in section.list do
                { value: listCard({ participants: item.participants, ... }) }
            end
        })
    }
end
```

**Grund:** Ohne for-Schleife kann Ninox Referenzen falsch auflösen – z.B. Teilnehmer-Badges von "Heute"-Karten erscheinen in "Morgen"-Karten. Die for-Schleife erzeugt pro Section einen sauberen Auswertungskontext, sodass jede Karte die richtigen Daten aus ihrer eigenen Section/Liste erhält.

#### ⚠️ **KRITISCH: if/else mit einzelnem Block vs. for-Schleife**

Wenn ein if-Zweig einen einzelnen Block und der else-Zweig eine for-Schleife enthält, muss der einzelne Block in `[{...}]` (eckige Klammern) gesetzt werden.

```javascript
// ❌ FEHLER: Unterschiedliche Typen (Object vs. Array)
if isEmpty then
    { value: "Leer" }  // Object
else
    for item in items do { value: item } end  // Array
end

// ✅ RICHTIG: Beide als Array
if isEmpty then
    [{ value: "Leer" }]  // Array mit einem Element
else
    for item in items do { value: item } end  // Array
end
```

**Grund:** Ninox erwartet bei if/else gleiche Typen. Die for-Schleife gibt ein Array zurück, also muss der einzelne Block auch als Array `[{...}]` definiert werden.

#### ⚠️ **KRITISCH: if direkt in Arrays OHNE extra `{`**

Bei bedingten Blöcken innerhalb von `blocks: [...]` darf das `if` NICHT in ein extra `{ }` gewrappt werden.

```javascript
// ❌ FALSCH: Extra { vor if
blocks: [{
        width: "100%",
        value: "immer sichtbar"
    }, {  // ← Dieses extra { ist FALSCH!
        if condition then
            {
                width: "100%",
                value: "bedingt"
            }
        end
    }  // ← Und dieses schließende } ist auch FALSCH!
]

// ✅ RICHTIG: if direkt im Array, kein extra Wrapper
blocks: [{
        width: "100%",
        value: "immer sichtbar"
    },
    if condition then
        {
            width: "100%",
            value: "bedingt"
        }
    end
]
```

**Grund:** Das `if...then...end` selbst gibt das Block-Objekt zurück (oder null). Ein Wrapping in `{ }` erzeugt eine ungültige Objekt-Struktur, die Ninox nicht parsen kann.

### Bedingte Blöcke - else-Zweig oft unnötig
Widget-`blocks`-Arrays ignorieren automatisch `null`/leere Werte. Daher sind leere `else`-Blöcke meist unnötig.

#### ❌ Verbose: Leere else-Blöcke
```javascript
blocks: [
    if condition then
        { /* ... */ }
    else
        {
            width: "0px",
            height: "0px",
            value: ""
        }
    end
]
```

#### ✅ Clean: Ohne else
```javascript
blocks: [
    if condition then
        { /* ... */ }
    end
]
```

**Ninox filtert automatisch:**
- `null` Werte
- Leere Arrays `[]`
- Undefined/falsy Ergebnisse

### Dynamisch vs. Statisch
Vermeide hardcoded, starre Lösungen. Nutze immer Schleifen und Arrays, um flexibel auf Datenstrukturen zu reagieren.

#### ❌ Statisch: Nur erste 2 Elemente
```javascript
blocks: [
    if count(teilnehmer) > 0 then
        { value: arcCustomBadge({ value: item(teilnehmer, 0).value }) }
    end,
    if count(teilnehmer) > 1 then
        { value: arcCustomBadge({ value: item(teilnehmer, 1).value }) }
    end
]
```

#### ✅ Dynamisch: Alle Elemente
```javascript
// Vorbereitung (Top-Level oder in Funktion):
let teilnehmerBadges := if teilnehmer then
    for t in teilnehmer do
        {
            width: "auto",
            height: "auto",
            value: arcCustomBadge({
                uniqueId: "badge-" + t.value,
                value: t.value,
                fontColor: if t.color then text(t.color) else "#FFFFFF" end,
                backgroundColor: if t.backgroundColor then text(t.backgroundColor) else "#3388FF" end
            })
        }
    end
else
    []
end;

// Verwendung im Layout:
blocks: [
    {
        value: arcCustomLayout({
            uniqueId: "teilnehmer-wrapper",
            blocks: teilnehmerBadges  // Dynamisch, alle Elemente
        })
    }
]
```

**Vorteile der dynamischen Lösung:**
- Funktioniert mit beliebig vielen Elementen (1, 5, 100...)
- Keine Code-Duplizierung
- Änderungen am Badge-Styling nur an einer Stelle
- Wiederverwendbar (Variable kann mehrfach genutzt werden)

### Pattern: Wiederverwendbare Badge-Arrays
Definiere Badge-Arrays als Variablen, um sie in mehreren Layouts zu verwenden (z.B. Card-Footer UND Popover-Header):

```javascript
function myComponent(data : any) do
    // Einmal definieren
    let typeBadges := if data.types then
        for typeItem in data.types do
            {
                width: "auto",
                height: "auto",
                value: arcCustomBadge({
                    uniqueId: data.id + "-type-" + typeItem.value,
                    value: text(typeItem.value),
                    fontColor: if typeItem.color then text(typeItem.color) else "#A114A8" end,
                    backgroundColor: if typeItem.backgroundColor then text(typeItem.backgroundColor) else "#FDDEFF" end
                })
            }
        end
    else
        []
    end;
    
    // Mehrfach verwenden
    arcCustomLayout({
        blocks: [
            { value: arcCustomLayout({ blocks: typeBadges }) },  // In Card
            { value: arcCustomLayout({ blocks: typeBadges }) }   // In Popover
        ]
    })
end
```

## 8. UI Patterns & Component Architecture

### Tab-basierte Navigation

Für komplexe UI-Komponenten mit mehreren Content-Bereichen (z.B. Popovers, Modals):

#### Tab-Konfiguration
```javascript
tabs: [{
    id: "termin",
    title: "Termin",
    hasComment: false,  // Flag für Badge-Display
    contentBlock: arcCustomLayout({
        uniqueId: "tab-termin-content",
        height: "100%",
        scrollSettings: { scrollY: true },
        blocks: [/* Content */]
    })
}, {
    id: "kommentare",
    title: "Kommentare",
    hasComment: currentRecord.CommentField != null and text(currentRecord.CommentField) != "",
    contentBlock: arcCustomLayout({
        uniqueId: "tab-kommentare-content",
        height: "100%",
        scrollSettings: { scrollY: true },
        blocks: [/* Content */]
    })
}]
```

#### Tab-Navigation Rendering
```javascript
// Tab-Buttons mit Badge-Support
blocks: for tab in popoverData.tabs do
    {
        width: "auto",
        height: "auto",
        value: arcCustomButton({
            uniqueId: popoverData.id + "-tab-" + tab.id,
            title: tab.title,
            backgroundColor: if popoverData.activeTab = tab.id then "#333333" else "#EBEDF5" end,
            fontColor: if popoverData.activeTab = tab.id then "#FFFFFF" else "#818599" end,
            showBadge: if tab.id = "kommentare" and tab.hasComment then true else false end,
            badgeTitle: "1",
            badgeColor: "#FFFFFF",
            badgeBackground: "#FF3B30",
            actions: [{
                type: "update",
                recordId: Nr,
                field: popoverData.tabActionField,
                value: tab.id
            }]
        })
    }
end
```

#### Dynamic Tab Content Display
```javascript
// Content-Bereich: Dynamisches Rendering basierend auf activeTab
{
    width: "100%",
    height: "fraction",  // Nimmt verfügbaren Platz
    value: let activeTabData := first(for tab in popoverData.tabs do
        if tab.id = popoverData.activeTab then
            tab
        end
    end);
    if activeTabData and activeTabData.contentBlock then
        html(activeTabData.contentBlock)  // ⚠️ html() Wrapper erforderlich!
    else
        arcCustomLayout({
            uniqueId: popoverData.id + "-empty-content",
            blocks: [{
                value: arcCustomText({
                    value: "Kein Content verfügbar.",
                    fontColor: "#999999"
                })
            }]
        })
    end
}
```

**Wichtig**: `html()` Wrapper ist erforderlich, wenn `contentBlock` als `any` Type übergeben wird, um Type-Kompatibilität zwischen Widget-Return und erwartetem Layout zu gewährleisten.

### Footer-Struktur in Popovers/Modals

Footer sollten **NICHT** Teil des scrollbaren Tab-Contents sein, sondern als separater Block am Ende positioniert werden.

#### ❌ Problematisch: Footer im Content
```javascript
contentBlock: arcCustomLayout({
    blocks: [
        { /* Content */ },
        { /* Footer Buttons */ }  // Scrollt mit → schlecht
    ]
})
```

#### ✅ Richtig: Footer als separates Property
```javascript
// 1. Footer als separates Property im Data-Objekt
{
    tabs: [...],
    footerBlock: arcCustomLayout({
        uniqueId: "popover-footer",
        height: "auto",  // Footer passt sich Inhalt an
        gap: "10px",
        paddingY: "10px",
        blocks: [
            if phoneNumber then
                { value: arcCustomButton({ title: "Anrufen", ... }) }
            end,
            if mapsUrl then
                { value: arcCustomButton({ title: "In Google Maps öffnen", ... }) }
            end
        ]
    })
}
```

```javascript
// 2. Footer im Popover-Layout (nach Content)
blocks: [
    { /* Header */ },
    { /* Tabs */ },
    { 
        width: "100%",
        height: "fraction",  // Content scrollbar
        value: /* Tab Content */
    },
    if popoverData.footerBlock then
        {
            width: "100%",
            height: "auto",  // Footer bleibt unten
            value: html(popoverData.footerBlock)
        }
    end
]
```

#### Layout-Struktur mit Footer
```
┌─────────────────────────────┐
│ Popover Header (auto)       │
├─────────────────────────────┤
│ Tabs Navigation (auto)      │
├─────────────────────────────┤
│ Tab Content (fraction)      │ ← scrollY: true
│   - Scrollbarer Bereich     │
│   - height: "fraction"      │
├─────────────────────────────┤
│ Footer (auto)               │ ← Immer sichtbar
│  [Action Button 1]          │
│  [Action Button 2]          │
└─────────────────────────────┘
```

**Vorteile:**
- Footer bleibt immer sichtbar (kein Scrollen nötig)
- Klare Trennung zwischen Content und Actions
- Bessere UX für Action-Buttons (z.B. "Anrufen", "In Maps öffnen")
- Unabhängiges Styling für Footer-Bereich

**Pattern-Zusammenfassung:**
1. Content-Bereich: `height: "fraction"` + `scrollY: true`
2. Footer-Bereich: `height: "auto"` + außerhalb des scrollbaren Content
3. Footer als `footerBlock` Property im Data-Objekt definieren
4. Footer mit `html(popoverData.footerBlock)` rendern

### Pagination für Listen/Kanban

Bei großen Datenmengen (z.B. Inbox mit vielen Mails) kann das Widget crashen. Lösung: `arcCustomPagination` mit `slice()`.

#### Pagination-Variablen oben definieren
```javascript
let maxEntriesPerPage := 20;

// Pro Liste/Swimlane
let listAll := (select Items where ...);
let totalCards := cnt(listAll);
let currentPage := if page_field then number(page_field) else 1 end;
let totalPages := ceil(totalCards / maxEntriesPerPage);
let listPaginated := slice(listAll, maxEntriesPerPage * (currentPage - 1), maxEntriesPerPage * currentPage);
```

#### Pagination in Config-Objekt
```javascript
let swimlaneConfig := [{
    id: "inbox",
    title: "Inbox",
    showPagination: totalCards > maxEntriesPerPage,  // Nur wenn nötig
    pagination: {
        currentPage: currentPage,
        totalPages: totalPages,
        totalCards: totalCards,
        fieldId: fieldId(Nr, "page_inbox")  // Number-Feld für aktuelle Seite
    },
    sections: [{
        title: "Items",
        cards: listPaginated.[{...}]  // Paginierte Liste verwenden
    }]
}];
```

#### Pagination Widget am Ende der Swimlane
```javascript
if swimlane.showPagination then
    {
        width: "100%",
        height: "auto",
        alignX: "center",
        value: arcCustomPagination({
            uniqueId: "pagination-" + text(swimlane.id),
            editable: true,
            recordId: Nr,
            fieldId: text(swimlane.pagination.fieldId),
            direction: "horizontal",
            title: swimlane.pagination.currentPage,
            value: swimlane.pagination.currentPage,
            total: swimlane.pagination.totalPages,
            totalPrefix: " von "
        })
    }
end
```

**Wichtig:**
- `showPagination` als boolean für konditionale Anzeige
- `slice(list, start, end)` für die paginierte Teilmenge
- Separates Number-Feld pro Swimlane/Liste (z.B. `page_inbox`, `page_bearbeiten`)
- `editable: true` erlaubt direkte Seiteneingabe

#### Pagination bei Filterwechsel zurücksetzen

⚠️ **Problem:** Wenn ein Filter gewechselt wird (z.B. Postfach), kann die aktuelle Seite höher sein als die neue Gesamtseitenzahl → leere Anzeige.

**Lösung:** Im Ninox Trigger "Nach Änderung" des Filterfelds die Seite zurücksetzen:

```ninox
// Trigger: Nach Änderung von "selectedPostfach"
'Aktuelle Seite' := 1
```

**Gilt für alle Filter die die Listengröße beeinflussen:**
- Postfach/Mailbox Auswahl
- Status Filter
- Kategorie Filter
- Bearbeiter Filter

### Empty States für Listen/Swimlanes

Wenn eine Liste/Swimlane leer ist, sollte ein Fallback-Text angezeigt werden.

#### Pattern: Bedingte Section-Anzeige + Empty State

⚠️ **WICHTIG:** Bei if/else mit unterschiedlichen Block-Typen (einzelner Block vs. for-Schleife) muss der einzelne Block in `[{...}]` (eckige Klammern) gesetzt werden, damit Ninox beide als Arrays erkennt.

```javascript
// Config: emptyMessage pro Swimlane
emptyMessage: "Keine Einträge im Posteingang",

// Rendering: if/else Pattern (NICHT if...end, for...end nebeneinander!)
let totalSectionCards := sum(for sec in swimlane.sections do count(sec.cards) end);
if totalSectionCards = 0 then
    [{  // ← Eckige Klammern um einzelnen Block!
        width: "100%",
        height: "100%",
        value: arcCustomLayout({
            uniqueId: "empty-" + swimlaneId,
            alignX: "center",
            alignY: "center",  // ← Für vertikale Zentrierung braucht man Layout!
            width: "100%",
            height: "100%",
            blocks: [{
                value: arcCustomText({ value: text(swimlane.emptyMessage), fontColor: "#999999" })
            }]
        })
    }]
else
    for section in swimlane.sections do
        if count(section.cards) > 0 then
            { /* Section mit Title und Cards */ }
        end
    end
end  // ← Ein end für das gesamte if/else
```

**Warum `[{...}]`?** Ninox erwartet bei if/else gleiche Typen. Die for-Schleife gibt ein Array zurück, also muss der einzelne Block auch als Array `[{...}]` definiert werden.

**Warum Layout für vertikale Zentrierung?** Blocks haben nur `alignX` für horizontale Ausrichtung. Für `alignY` (vertikale Zentrierung) muss ein `arcCustomLayout` Wrapper verwendet werden.

### Reset-Button in Select ausblenden

Manche Selects haben "Alle" bereits als Record-Option und dürfen nicht auf null zurückgesetzt werden.

```javascript
// Config: hideReset pro Filter
filters: [{
    placeholder: "Posteingang",
    hideReset: true,  // Kein Reset-Button
    items: [...]
}, {
    placeholder: "Status",
    hideReset: false,  // Reset-Button "Alle" anzeigen
    items: [...]
}]

// Rendering: reset.hide aus Config lesen
reset: {
    title: "Alle",
    value: "",
    hide: if filter.hideReset then true else false end
}
```

## 9. Responsive Design: isMobile Pattern mit ninoxApp()

### Plattform-Erkennung

Verwende `ninoxApp()` um zwischen Mobile und Desktop/Tablet zu unterscheiden:

```javascript
let isMobile := ninoxApp() = "iphone" or ninoxApp() = "android";
```

Rückgabewerte von `ninoxApp()`: `"web"`, `"mac"`, `"iphone"`, `"ipad"`, `"android"`, `"tab"`, `"server"`.

### Desktop Layout Shell

Auf Desktop/Tablet: Zweispaltiges Layout:
- **Linke Sidebar** (fixe Breite, z.B. `370px`): Mobile-Ansichten als Sidebar adaptiert
- **Rechter Content-Bereich** (`width: "fraction"`): Desktop-spezifischer Content mit Header (fixe Höhe), Content (fraction), Footer (auto)

### isMobile Parameter in Funktionen

`isMobile` über das Data-Objekt an alle Funktionen weiterreichen, die plattformspezifische Anpassungen benötigen:

```javascript
--- In Funktion: Styles bedingt setzen ---
styles: if data.isMobile then
    "overflow-x: hidden; max-width: 400px; min-height: 700px;position:relative;"
else
    "overflow-x: hidden; min-height: 700px;position:relative;"
end,
```

### Views-Architektur (Einheitliche Navigation)

Zwei-Ebenen-Navigationssystem:
1. **`activeView`** (aus State abgeleitet): Bestimmt den Top-Level-Kontext (dashboard, ticket, customer)
2. **`activeTab`** (aus `helper_activeTab`): Wählt den Tab innerhalb der aktuellen View

Alle Navigationsaktionen schreiben in ein einziges Feld `helper_activeTab` über `tabActionField`.

```javascript
--- activeView wird aus globalem State abgeleitet, nicht in einem Feld gespeichert ---
let activeView := if helper_currentCustomer then
        "customer"
    else
        if currentTicket then "ticket" else "dashboard" end
    end;

--- Alle Tabs nutzen das gleiche Action-Feld ---
let tabActionField := fieldId(Nr, "helper_activeTab");
let activeTabValue := if helper_activeTab then helper_activeTab else "" end;
```

### View-Funktionen mit Lazy Content Loading

**Kritisch für Performance**: Schweren Content in View-Funktionen mit `if data.active then ... end` Guards wrappen. Das verhindert, dass Ninox teure Widget-Berechnungen für inaktive Views auswertet (da `let`-Variablen in Ninox eager evaluiert werden).

```javascript
function viewTicket(data : any) do
    if data.active then
        let activeTab := if data.activeTab then data.activeTab else "ticket" end;
        {
            desktop: {
                sidebar: { content: heavyWidget(), footer: null },
                main: { content: mainWidget(), header: null, footer: footerWidget(), contentSidebar: null }
            },
            mobile: {
                main: mobileWidget(),
                footer: null,
                header: null
            }
        }
    end
end;
```

**Warum Funktionen statt Inline-JSON?**: Wenn man `let myWidget := expensiveWidget();` auf Top-Level setzt und es im JSON mit `if activeView = "ticket" then myWidget end` referenziert, evaluiert Ninox `myWidget` trotzdem. Durch das Wrappen in eine Funktion mit `data.active`-Check wird die teure Berechnung nur bei aktiver View ausgelöst.

### Views-Konfiguration

Views als Array von Config-Objekten organisieren, jedes mit eigenen `navTabs` und lazy-geladenem `content`:

```javascript
let views := [{
        id: "dashboard",
        active: activeView = "dashboard",
        defaultTab: "cockpit",
        navTabs: [{ id: "cockpit", title: "Cockpit", visible: true, active: ..., actionField: tabActionField }, ...],
        content: viewDashboard({ active: activeView = "dashboard", activeTab: activeTabValue, ... })
    }, {
        id: "ticket",
        active: activeView = "ticket",
        navTabs: [{ id: "ticket", title: "Ticket", visible: true, active: ..., actionField: tabActionField }, ...],
        content: viewTicket({ active: activeView = "ticket", activeTab: activeTabValue, ... })
    }];
```

### Generisches Rendering aus Views-Config

Aktuelle View auflösen und plattformspezifischen Content rendern:

```javascript
let currentView := first(for v in views do if v.active then v end end);
let currentNavTabs := if currentView then currentView.navTabs else [] end;
let viewContent := if currentView then currentView.content else null end;

if isMobile then
    if viewContent and viewContent.mobile and viewContent.mobile.main then
        html(viewContent.mobile.main)
    end
else
    desktopLayout({
            sidebarContent: viewContent.desktop.sidebar.content,
            rightHeader: desktopTicketHeader({ tabs: currentNavTabs, tabRecordId: Nr, ... }),
            rightContent: viewContent.desktop.main.content,
            rightFooter: viewContent.desktop.main.footer
        })
end
```

Jede View-Funktion gibt sowohl `desktop`- als auch `mobile`-Content-Strukturen zurück. Der generische Renderer wählt die richtige basierend auf `isMobile`.

## 10. Helper-Feld Namenskonvention

Konsistentes Namensschema für Helper-Felder:

| Pattern | Beispiel | Verwendung |
|---------|----------|------------|
| `helper_current{Entity}` | `helper_currentCustomer` | Aktuell ausgewählter/aktiver Datensatz (ID) |
| `helper_active{Feature}` | `helper_activeView` | Aktiver Tab/View/Modus |
| `helper_selected{Entity}` | `helper_selectedTicket` | Ausgewähltes Element für Detail/Popover |
| `trigger_{action}` | `trigger_delete` | Boolean-Trigger-Felder für Ninox-Aktionen |

Plattform-spezifische Präfixe wie `desktop_` oder `mobile_` sowie kontext-spezifische wie `popover_` oder `filter_` in Feldnamen vermeiden. Generische Namen verwenden, damit dasselbe Feld plattformübergreifend funktioniert.

### Refactoring-Learnings (Detail-/List-Views)

**Skeleton-first-Architektur**: Layout-Shell (panelLayout, fullLayout) zuerst mit Platzhaltern bauen, dann reale Komponenten schrittweise integrieren. Vermeidet "alter Code läuft weiter" und ermöglicht sauberes Testen.

**Shared Data Objects**: Ein einziges `ticketData` (oder `currentTicket`) Objekt wenn ein Ticket ausgewählt ist. Alle Sub-Views (Details, Notizen, Kommentare, Historie) konsumieren daraus. Einmal berechnen, überall wiederverwenden.

**View-Level-Variablen-Scoping**: Variablen wie `ticketHeader`, `ticketSidebarContent`, `ticketFooter` innerhalb von `if activeView = "ticket" then ... end` werden nur bei aktiver View evaluiert. Verhindert eager evaluation schwerer Widgets für inaktive Views.

**Generische Komponenten-Namen**: `ticketSidebarHeader` statt `mobileTicketHeader` oder `popoverHeader`. Dieselbe Komponente dient Desktop-Sidebar und Mobile-Panel; später für andere Entitäten wiederverwendbar.

**Array-Projektion für Sections**: `list[visible = true and count(list) > 0].[{ block }]` direkt in blocks für effiziente Iteration. Query innerhalb `if hasSearchFilter then ... else [] end` für Performance, wenn eine "Später"-Section nur bei Suche relevant ist.

**Select-Items-Syntax**: Für arcCustomSelect `(select Table).[{ title: ..., active: ..., value: ... }]` verwenden, nicht `for m in select ... do { id, title } end`. Das `active`-Flag prüft `contains(numbers(current.Field), number(Nr))` bei Multi-Select.

**arcCustomSelect currentValue bei Verknüpfungsfeldern**: Wenn das Select-Feld eine Relation ist, muss `currentValue` das Anzeigefeld der verknüpften Tabelle nutzen, nicht `text(record.Relation)`. Beispiel: `currentValue: if record.Kategorie then text(record.Kategorie.Titel) else "" end`.

**Conditional Tab `main` für Detail-Views**: Wenn ein Tab sowohl Listen- als auch Detail-Ansicht hat, die `main`-Property conditional machen: `main: if detailActive then { showNav: false, headerLeft: backBtn, headerRight: actionBtn, content: detailContent, contentRight: detailSidebar, footer: detailFooter } else { showNav: true, content: listContent, ... } end`. Nutzt die `desktopMainLayout`-Slots (headerLeft, headerRight, contentRight, footer) statt alles in eine einzige Content-Funktion zu packen.

**Detail-View-Rendering auf Tab-Ebene, nicht in Content-Funktionen**: Nicht innerhalb von `untersuchungenContent()` zwischen Liste und Detail branchen. Content-Funktionen auf eine Aufgabe fokussieren (Liste ODER Detail) und die Tab-Definition entscheiden lassen, was gerendert wird. Ermöglicht korrekte Nutzung von Sidebar/Footer/Header-Slots.

## 11. Dokumentation für LLMs

Wenn Code generiert wird, muss er:
1.  Kompilierbar in Ninox sein (kein echtes JS).
2.  Die Widget-Referenz strikt befolgen.