Advanced on Palmyra

Building filterable dashboards

Mon, 01 Jan 0001 00:00:00 +0000

Building filterable dashboards#

A dashboard with multiple chart widgets, a shared filter bar, and drill-down to detail grids. The charts consume ChartStore endpoints; the filter state is lifted into React context so every widget re-fetches when a filter changes.

Architecture#

FilterBar (shared state)
  ├── SummaryCard (total projects, total value, ...)
  ├── PieChart    (projects by stage)
  ├── BarChart    (monthly progress)
  └── GridDrillDown (top vendors → click → vendor detail)

Shared filter context#

// src/pages/dashboard/DashboardFilterContext.tsx
import { createContext, useContext, useState, type ReactNode } from 'react';

interface Filters {
  departmentId?: number;
  stage?:        string;
  contractorId?: number;
  year?:         number;
}

const Ctx = createContext<{
  filters:    Filters;
  setFilters: (f: Filters) => void;
}>({ filters: {}, setFilters: () => {} });

export function DashboardFilterProvider({ children }: { children: ReactNode }) {
  const [filters, setFilters] = useState<Filters>({});
  return <Ctx.Provider value={{ filters, setFilters }}>{children}</Ctx.Provider>;
}

export const useDashboardFilters = () => useContext(Ctx);

Filter bar#

// src/pages/dashboard/FilterBar.tsx
import { Group } from '@mantine/core';
import { MantineSelect, MantineServerLookup } from '@palmyralabs/rt-forms-mantine';
import { PalmyraForm } from '@palmyralabs/rt-forms';
import { useDashboardFilters } from './DashboardFilterContext';

export default function FilterBar() {
  const { setFilters } = useDashboardFilters();

  const onFormChange = (data: any) => setFilters(data);

  return (
    <PalmyraForm formData={{}} onValidChange={() => {}}>
      <Group>
        <MantineServerLookup
          attribute="departmentId"
          label="Department"
          queryOptions={{ endPoint: '/department', queryAttribute: 'name',
                          labelAttribute: 'name', idAttribute: 'id' }}
          onChange={(_v, rec) => setFilters(prev => ({ ...prev, departmentId: rec?.id }))}
        />
        <MantineSelect
          attribute="stage"
          label="Stage"
          options={[
            { value: 'PLANNING', label: 'Planning' },
            { value: 'EXECUTION', label: 'Execution' },
            { value: 'COMPLETED', label: 'Completed' },
          ]}
          onChange={(v) => setFilters(prev => ({ ...prev, stage: v }))}
        />
      </Group>
    </PalmyraForm>
  );
}

// src/pages/dashboard/ProjectsByStageChart.tsx
import { useEffect, useState } from 'react';
import { PieChart } from '@palmyralabs/rt-apexchart';   // or rt-chartjs
import AppStoreFactory from '../../wire/StoreFactory';
import { useDashboardFilters } from './DashboardFilterContext';

export default function ProjectsByStageChart() {
  const { filters } = useDashboardFilters();
  const [data, setData] = useState<any[]>([]);

  useEffect(() => {
    const store = AppStoreFactory.getChartStore({}, '/dashboard/projects-by-stage');
    store.query({ filter: filters }).then(setData);
  }, [filters]);

  return (
    <PieChart
      data={data}
      labelKey="stage"
      valueKey="count"
      title="Projects by Stage"
    />
  );
}

Summary cards#

// src/pages/dashboard/SummaryCards.tsx
import { useEffect, useState } from 'react';
import { Group, Paper, Text, Title } from '@mantine/core';
import AppStoreFactory from '../../wire/StoreFactory';
import { useDashboardFilters } from './DashboardFilterContext';

export default function SummaryCards() {
  const { filters } = useDashboardFilters();
  const [stats, setStats] = useState({ projects: 0, totalValue: 0, vendors: 0 });

  useEffect(() => {
    const store = AppStoreFactory.getChartStore({}, '/dashboard/summary');
    store.query({ filter: filters }).then(rows => {
      if (rows[0]) setStats(rows[0]);
    });
  }, [filters]);

  return (
    <Group>
      <Paper p="md" shadow="xs"><Title order={4}>{stats.projects}</Title><Text>Projects</Text></Paper>
      <Paper p="md" shadow="xs"><Title order={4}>{stats.totalValue.toLocaleString()}</Title><Text>Total Value</Text></Paper>
      <Paper p="md" shadow="xs"><Title order={4}>{stats.vendors}</Title><Text>Vendors</Text></Paper>
    </Group>
  );
}

Composing the dashboard page#

// src/pages/dashboard/DashboardPage.tsx
import { DashboardFilterProvider } from './DashboardFilterContext';
import FilterBar from './FilterBar';
import SummaryCards from './SummaryCards';
import ProjectsByStageChart from './ProjectsByStageChart';
import MonthlyProgressChart from './MonthlyProgressChart';

export default function DashboardPage() {
  return (
    <DashboardFilterProvider>
      <div style={{ padding: 16 }}>
        <FilterBar />
        <SummaryCards />
        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16, marginTop: 16 }}>
          <ProjectsByStageChart />
          <MonthlyProgressChart />
        </div>
      </div>
    </DashboardFilterProvider>
  );
}

Key patterns#

One filter context, many consumers. Every chart re-fetches when filters changes — no prop-drilling, no duplicated state.
ChartStore per widget. Each chart hits its own endpoint. The backend can optimise each query independently.
Drill-down to grid. On chart click, navigate to a PalmyraGrid pre-filtered to the clicked segment — pass the filter via initParams.

See also: PalmyraChartStore, PalmyraGrid.

Custom DataGridControls

Mon, 01 Jan 0001 00:00:00 +0000

Custom DataGridControls#

SummaryGrid and PalmyraGrid accept a DataGridControls prop — a React component that renders the toolbar above the grid. Build your own to add quick search, filter toggles, export buttons, and navigation controls, then reuse it across every grid page.

The contract#

interface DataGridPluginOptions {
  queryRef:    RefObject<IPageQueryable>;
  columns:     ColumnDefinition[];
  // plus anything your getPluginOptions() returns
}

The grid passes queryRef so your toolbar can call refresh(), setFilter(...), setQuickSearch(...), and export(...).

// src/common/components/gridControl/AppDataGridControls.tsx
import { Button, Group, TextInput } from '@mantine/core';
import { IconPlus, IconFilter, IconDownload, IconArrowLeft } from '@tabler/icons-react';
import { useState } from 'react';
import { useNavigate } from 'react-router-dom';
import { FilterForm } from '@palmyralabs/rt-forms-mantine';

export default function AppDataGridControls(o: any) {
  const navigate = useNavigate();
  const [search, setSearch]       = useState('');
  const [filterOpen, setFilterOpen] = useState(false);

  const opts = o.getPluginOptions?.() ?? {};

  const handleSearch = (value: string) => {
    setSearch(value);
    o.queryRef?.current?.setQuickSearch(value);
  };

  const handleExport = () => {
    o.queryRef?.current?.export({ format: 'csv' });
  };

  return (
    <>
      <Group justify="space-between" mb="sm">
        <Group>
          {opts.backOption !== false && (
            <Button variant="subtle" leftSection={<IconArrowLeft size={16} />}
                    onClick={() => navigate(-1)}>Back</Button>
          )}
          <TextInput placeholder="Quick search" size="sm"
                     value={search} onChange={e => handleSearch(e.currentTarget.value)} />
        </Group>
        <Group>
          <Button variant="light" leftSection={<IconFilter size={16} />}
                  onClick={() => setFilterOpen(!filterOpen)}>Filter</Button>
          {opts.export?.visible !== false && (
            <Button variant="light" leftSection={<IconDownload size={16} />}
                    onClick={handleExport}>Export CSV</Button>
          )}
          {opts.onNewClick && (
            <Button leftSection={<IconPlus size={16} />}
                    onClick={opts.onNewClick}>{opts.addText ?? 'Add'}</Button>
          )}
        </Group>
      </Group>
      {filterOpen && (
        <FilterForm
          queryRef={o.queryRef}
          columns={o.columns}
          column={2}
          onClose={() => setFilterOpen(false)}
        />
      )}
    </>
  );
}

Using it on a grid page#

<SummaryGrid
  title="Projects"
  columns={projectColumns}
  options={{ endPoint: '/project' }}
  pageSize={[15, 30, 45]}
  gridRef={gridRef}
  DataGridControls={AppDataGridControls}
  getPluginOptions={() => ({
    addText:    'New Project',
    onNewClick: open,
    export:     { visible: true },
    backOption: false,
  })}
/>

For embedded grids (inside a view page, alongside other content), a slimmer toolbar without back/add:

File upload with drag-and-drop

Mon, 01 Jan 0001 00:00:00 +0000

File upload with drag-and-drop#

Uploading files to a Palmyra-backed API using react-dropzone and the store’s post() method. The store handles the FormData encoding, error handling, and the refresh signal.

Install#

npm install react-dropzone

Reusable dropzone component#

// src/components/fileUpload/FileDropZone.tsx
import { useCallback, useState } from 'react';
import { useDropzone } from 'react-dropzone';
import { Button, Group, Paper, Text, Stack } from '@mantine/core';
import { IconUpload, IconFile, IconX } from '@tabler/icons-react';
import { toast } from 'react-toastify';
import AppStoreFactory from '../../wire/StoreFactory';

interface Props {
  endPoint:    string;
  parentId?:   string | number;
  maxFiles?:   number;           // default 5
  maxSizeMB?:  number;           // default 5
  accept?:     Record<string, string[]>;
  onUploaded?: () => void;
}

const DEFAULT_ACCEPT = {
  'application/pdf':  ['.pdf'],
  'image/png':        ['.png'],
  'image/jpeg':       ['.jpg', '.jpeg'],
  'application/msword': ['.doc', '.docx'],
};

export default function FileDropZone(props: Props) {
  const { endPoint, parentId, maxFiles = 5, maxSizeMB = 5, onUploaded } = props;
  const [files, setFiles] = useState<File[]>([]);
  const [uploading, setUploading] = useState(false);

  const onDrop = useCallback((accepted: File[]) => {
    setFiles(prev => [...prev, ...accepted].slice(0, maxFiles));
  }, [maxFiles]);

  const { getRootProps, getInputProps, isDragActive } = useDropzone({
    onDrop,
    accept:   props.accept ?? DEFAULT_ACCEPT,
    maxSize:  maxSizeMB * 1024 * 1024,
    maxFiles,
  });

  const removeFile = (index: number) => {
    setFiles(prev => prev.filter((_, i) => i !== index));
  };

  const upload = async () => {
    if (files.length === 0) return;
    setUploading(true);

    try {
      const store = AppStoreFactory.getFormStore({}, endPoint);

      for (const file of files) {
        const formData = new FormData();
        formData.append('file', file);
        if (parentId) formData.append('parentId', String(parentId));
        await store.post(formData as any);
      }

      toast.success(`${files.length} file(s) uploaded`);
      setFiles([]);
      onUploaded?.();
    } catch {
      toast.error('Upload failed');
    } finally {
      setUploading(false);
    }
  };

  return (
    <Stack>
      <Paper
        {...getRootProps()}
        p="xl"
        withBorder
        style={{ borderStyle: 'dashed', cursor: 'pointer',
                 backgroundColor: isDragActive ? '#f0f9ff' : undefined }}
      >
        <input {...getInputProps()} />
        <Stack align="center" gap="xs">
          <IconUpload size={32} color="gray" />
          <Text c="dimmed" size="sm">
            {isDragActive
              ? 'Drop files here…'
              : `Drag & drop up to ${maxFiles} files, or click to browse (max ${maxSizeMB} MB each)`}
          </Text>
        </Stack>
      </Paper>

      {files.map((f, i) => (
        <Group key={i} justify="space-between">
          <Group gap="xs">
            <IconFile size={16} />
            <Text size="sm">{f.name}</Text>
            <Text size="xs" c="dimmed">({(f.size / 1024).toFixed(0)} KB)</Text>
          </Group>
          <IconX size={14} style={{ cursor: 'pointer' }} onClick={() => removeFile(i)} />
        </Group>
      ))}

      {files.length > 0 && (
        <Button onClick={upload} loading={uploading}>Upload {files.length} file(s)</Button>
      )}
    </Stack>
  );
}

Using it on a detail page#

// Inside EmployeeViewPage or similar
<FileDropZone
  endPoint="/employee/{id}/documents"
  parentId={params.id}
  maxFiles={3}
  maxSizeMB={10}
  accept={{ 'application/pdf': ['.pdf'] }}
  onUploaded={() => documentGridRef.current?.refresh()}
/>

Backend endpoint#

The backend receives multipart/form-data. A plain Spring controller alongside the Palmyra handler works well:

Workflow timeline visualization

Mon, 01 Jan 0001 00:00:00 +0000

Workflow timeline visualization#

The frontend counterpart to the backend approval workflow. A modal that fetches the workflow steps for a record and renders them as a Mantine timeline.

Component#

// src/components/workflow/WorkflowTimeline.tsx
import { useEffect, useState } from 'react';
import { Badge, Button, Modal, Text, Timeline } from '@mantine/core';
import { IconCheck, IconX, IconClock } from '@tabler/icons-react';
import AppStoreFactory from '../../wire/StoreFactory';

interface Props {
  entityId:  string | number;
  endPoint:  string;            // e.g. '/invoice/{invoiceId}/workflow'
  open:      boolean;
  onClose:   () => void;
  title?:    string;
}

const statusIcon: Record<string, any> = {
  COMPLETED: <IconCheck size={14} />,
  APPROVED:  <IconCheck size={14} />,
  REJECTED:  <IconX size={14} />,
  PENDING:   <IconClock size={14} />,
};

const statusColor: Record<string, string> = {
  COMPLETED: 'green', APPROVED: 'green', REJECTED: 'red', PENDING: 'gray',
};

interface Step {
  stepOrder:  number;
  groupName:  string;
  status:     string;
  actedBy?:   string;
  actedAt?:   string;
  remarks?:   string;
}

export default function WorkflowTimeline({ entityId, endPoint, open, onClose, title }: Props) {
  const [steps, setSteps] = useState<Step[]>([]);

  useEffect(() => {
    if (!open) return;
    const store = AppStoreFactory.getGridStore(
      { endPointOptions: { invoiceId: entityId } },
      endPoint
    );
    store.query({ sortOrder: { stepOrder: 'asc' }, limit: 100 }).then(r => {
      setSteps(r.result ?? []);
    });
  }, [open, entityId]);

  return (
    <Modal opened={open} onClose={onClose} title={title ?? 'Approval History'} size="lg">
      {steps.length === 0 ? (
        <Text c="dimmed">No workflow history found.</Text>
      ) : (
        <Timeline active={steps.length - 1} bulletSize={24} lineWidth={2}>
          {steps.map((step, i) => (
            <Timeline.Item
              key={i}
              bullet={statusIcon[step.status] ?? <IconClock size={14} />}
              color={statusColor[step.status] ?? 'gray'}
              title={
                <>
                  {step.groupName}
                  <Badge ml="xs" size="xs" color={statusColor[step.status] ?? 'gray'}>
                    {step.status}
                  </Badge>
                </>
              }
            >
              {step.actedBy && <Text size="sm">By: {step.actedBy}</Text>}
              {step.actedAt && <Text size="xs" c="dimmed">{new Date(step.actedAt).toLocaleString()}</Text>}
              {step.remarks && <Text size="sm" mt="xs" fs="italic">{step.remarks}</Text>}
            </Timeline.Item>
          ))}
        </Timeline>
      )}
    </Modal>
  );
}

Using it on a detail page#

import { useDisclosure } from '@mantine/hooks';
import WorkflowTimeline from '../../components/workflow/WorkflowTimeline';

function InvoiceViewPage() {
  const params = useParams();
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <>
      <Button variant="subtle" onClick={open}>View approval history</Button>
      <WorkflowTimeline
        entityId={params.id!}
        endPoint="/invoice/{invoiceId}/workflow"
        open={opened}
        onClose={close}
        title="Invoice Approval History"
      />
    </>
  );
}

Client-side Excel export

Mon, 01 Jan 0001 00:00:00 +0000

Client-side Excel export#

When export is bounded (one page of grid data, already loaded) and server-side ExcelHandler / CsvHandler would be overkill, build the workbook in the browser using the xlsx library.

Install#

npm install xlsx file-saver
npm install -D @types/file-saver

Export utility#

// src/utils/ExcelExport.ts
import * as XLSX from 'xlsx';
import { saveAs } from 'file-saver';

export interface ExportColumn {
  key:   string;     // attribute name on the row object
  label: string;     // column header in the workbook
}

export function exportToExcel(
  rows:     Record<string, any>[],
  columns:  ExportColumn[],
  fileName: string = 'export',
  options?: { sheetName?: string; includeTotal?: string[] }
) {
  // Map rows to labelled columns
  const data = rows.map(row =>
    Object.fromEntries(columns.map(c => [c.label, row[c.key] ?? '']))
  );

  // Optional total row
  if (options?.includeTotal) {
    const totals: Record<string, any> = {};
    columns.forEach(c => {
      if (options.includeTotal!.includes(c.key)) {
        totals[c.label] = rows.reduce(
          (sum, r) => sum + (Number(r[c.key]) || 0), 0
        );
      } else {
        totals[c.label] = c === columns[0] ? 'TOTAL' : '';
      }
    });
    data.push(totals);
  }

  const ws = XLSX.utils.json_to_sheet(data);
  const wb = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(wb, ws, options?.sheetName ?? 'Sheet1');
  const buf = XLSX.write(wb, { bookType: 'xlsx', type: 'array' });
  saveAs(new Blob([buf], { type: 'application/octet-stream' }), `${fileName}.xlsx`);
}

import { exportToExcel, type ExportColumn } from '../../utils/ExcelExport';

const exportColumns: ExportColumn[] = [
  { key: 'loginName',      label: 'Email' },
  { key: 'firstName',      label: 'First Name' },
  { key: 'lastName',       label: 'Last Name' },
  { key: 'departmentCode', label: 'Department' },
  { key: 'status',         label: 'Status' },
];

// Inside your custom DataGridControls:
const handleExport = () => {
  const rows = o.queryRef?.current?.getCurrentData() ?? [];
  exportToExcel(rows, exportColumns, 'employees', {
    sheetName: 'Employees',
  });
};

<Button onClick={handleExport}>Export Excel</Button>

When to use client-side vs. server-side export#

Client-side (`xlsx` + `file-saver`)	Server-side (`CsvHandler` / `ExcelHandler`)
Already-loaded rows (one page)	Full result set across all pages
No server round-trip	Streams from the database — handles millions of rows
Browser memory is the limit	Server memory scales independently
Quick to implement	Needs a dedicated handler + `@CrudMapping`

Use both in the same app: the grid toolbar’s “Export current page” calls the client-side utility; a separate “Export all” button points at the server-side handler URL.

Frontend ACL with permission codes

Mon, 01 Jan 0001 00:00:00 +0000

Frontend ACL with permission codes#

The backend’s @Permission and ACL extension control what the server allows. The frontend’s job is to hide controls the user can’t use — buttons, menu items, grid actions — so they don’t click something that returns 403. This page shows the full lifecycle: login → cache → hook → conditional rendering → refresh.

Permission code config#

Centralise every code so they’re searchable and rename-safe:

// src/config/Permissions.ts
export const Permission = {
  project: {
    GET_ALL: 'PRJ001',
    CREATE:  'PRJ002',
    UPDATE:  'PRJ003',
    DELETE:  'PRJ004',
    EXPORT:  'PRJ005',
    APPROVE: 'PRJ006',
  },
  invoice: {
    GET_ALL: 'INV001',
    CREATE:  'INV002',
    APPROVE: 'INV003',
  },
};

These codes match the values stored in the backend’s ACL tables. The backend returns them at login (or via a dedicated /acl/permissions endpoint).

Dark/light theme switching

Mon, 01 Jan 0001 00:00:00 +0000

Dark/light theme switching#

A theme toggle that persists to localStorage, syncs across components via Palmyra’s topic pub-sub, and allows specific routes (e.g. payment pages) to force a mode.

Theme context#

// src/wire/ThemeProvider.tsx
import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
import { topic } from '@palmyralabs/ts-utils';
import { useLocation } from 'react-router-dom';

type Theme = 'light' | 'dark';
const STORAGE_KEY = 'palmyra.theme';

// Routes that must always render in light mode (e.g. payment forms, print views)
const FORCE_LIGHT_ROUTES = ['/payment', '/print'];

const ThemeCtx = createContext<{
  theme:  Theme;
  toggle: () => void;
}>({ theme: 'light', toggle: () => {} });

export function ThemeProvider({ children }: { children: ReactNode }) {
  const location = useLocation();
  const [theme, setTheme] = useState<Theme>(
    () => (localStorage.getItem(STORAGE_KEY) as Theme) || 'light'
  );

  // Check route overrides
  const forcedLight = FORCE_LIGHT_ROUTES.some(r => location.pathname.startsWith(r));
  const effectiveTheme = forcedLight ? 'light' : theme;

  useEffect(() => {
    document.documentElement.classList.toggle('dark', effectiveTheme === 'dark');
    document.body.setAttribute('data-theme', effectiveTheme);
  }, [effectiveTheme]);

  const toggle = () => {
    const next: Theme = theme === 'light' ? 'dark' : 'light';
    localStorage.setItem(STORAGE_KEY, next);
    setTheme(next);
    topic.publish('theme:changed', next);
  };

  // Listen for changes from other tabs / components
  useEffect(() => {
    const unsub = topic.subscribe('theme:changed', (t: Theme) => setTheme(t));
    return unsub;
  }, []);

  return (
    <ThemeCtx.Provider value={{ theme: effectiveTheme, toggle }}>
      {children}
    </ThemeCtx.Provider>
  );
}

export const useTheme = () => useContext(ThemeCtx);

Toggle button#

// src/components/ThemeToggle.tsx
import { ActionIcon } from '@mantine/core';
import { IconSun, IconMoon } from '@tabler/icons-react';
import { useTheme } from '../wire/ThemeProvider';

export default function ThemeToggle() {
  const { theme, toggle } = useTheme();
  return (
    <ActionIcon variant="subtle" onClick={toggle} aria-label="Toggle theme">
      {theme === 'dark' ? <IconSun size={18} /> : <IconMoon size={18} />}
    </ActionIcon>
  );
}

Wiring#

Wrap inside your router (after BrowserRouter) so useLocation is available:

Multilingual support with i18n

Mon, 01 Jan 0001 00:00:00 +0000

Multilingual support with react-i18next#

When your application serves multiple language communities — a citizen portal with Hindi and English, an ERP with local + English — add react-i18next alongside the Palmyra component stack. Form labels, error messages, button text, and grid headers all pull from translation files.

Install#

npm install react-i18next i18next i18next-browser-languagedetector

Setup#

// src/i18n/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

import en from './locales/en.json';
import hi from './locales/hi.json';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: { en: { translation: en }, hi: { translation: hi } },
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
    detection: {
      order: ['localStorage', 'navigator'],
      caches: ['localStorage'],
    },
  });

export default i18n;

Import it once in main.tsx:

In-app discussion threads

Mon, 01 Jan 0001 00:00:00 +0000

In-app discussion threads#

A chat-style clarification thread attached to any entity — built entirely on Palmyra form stores. No WebSocket needed; the UI polls (or refreshes on action) via the standard PalmyraStoreFactory.

Backend#

A simple message table + a Palmyra handler:

CREATE TABLE discussion (
  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
  entity_type VARCHAR(32)  NOT NULL,
  entity_id   BIGINT       NOT NULL,
  sender      VARCHAR(128) NOT NULL,
  message     TEXT         NOT NULL,
  created_at  TIMESTAMP    NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_disc_entity ON discussion(entity_type, entity_id);

@PalmyraType(type = "Discussion", table = "discussion")
public class DiscussionModel {
    @PalmyraField(primaryKey = true) private Long id;
    @PalmyraField private String entityType;
    @PalmyraField private Long entityId;
    @PalmyraField private String sender;
    @PalmyraField private String message;
    @PalmyraField(drop = DropMode.INCOMING) private Instant createdAt;
}

@Component
@CrudMapping(mapping = "/discussion", type = DiscussionModel.class)
public class DiscussionHandler extends AbstractHandler
        implements QueryHandler, CreateHandler {

    @Override
    public Tuple preCreate(Tuple tuple, HandlerContext ctx) {
        tuple.setAttribute("sender", authProvider.getUser());
        tuple.setAttribute("createdAt", Instant.now());
        return tuple;
    }

    @Override
    public QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx) {
        filter.addOrderAsc("createdAt");
        return filter;
    }
}

React chat component#

// src/components/chat/DiscussionThread.tsx
import { useEffect, useRef, useState } from 'react';
import { Button, Group, Paper, ScrollArea, Stack, Text, Textarea } from '@mantine/core';
import AppStoreFactory from '../../wire/StoreFactory';

interface Props {
  entityType: string;
  entityId:   string | number;
  currentUser: string;
}

interface Message {
  id: number;
  sender: string;
  message: string;
  createdAt: string;
}

export default function DiscussionThread({ entityType, entityId, currentUser }: Props) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [draft, setDraft]       = useState('');
  const [sending, setSending]   = useState(false);
  const scrollRef               = useRef<HTMLDivElement>(null);

  const load = () => {
    const store = AppStoreFactory.getGridStore({}, '/discussion');
    store.query({
      filter: { entityType, entityId },
      sortOrder: { createdAt: 'asc' },
      limit: 200,
    }).then(r => {
      setMessages(r.result ?? []);
      setTimeout(() => scrollRef.current?.scrollTo({ top: 999999, behavior: 'smooth' }), 100);
    });
  };

  useEffect(load, [entityType, entityId]);

  const send = async () => {
    if (!draft.trim()) return;
    setSending(true);
    const store = AppStoreFactory.getFormStore({}, '/discussion');
    await store.post({ entityType, entityId, message: draft.trim() } as any);
    setDraft('');
    setSending(false);
    load();
  };

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(); }
  };

  return (
    <Paper p="md" withBorder>
      <ScrollArea h={300} viewportRef={scrollRef}>
        <Stack gap="xs">
          {messages.map(m => (
            <div key={m.id}
                 style={{ alignSelf: m.sender === currentUser ? 'flex-end' : 'flex-start',
                          maxWidth: '70%' }}>
              <Paper p="xs" radius="md"
                     bg={m.sender === currentUser ? 'blue.1' : 'gray.1'}>
                <Text size="xs" fw={600} c="dimmed">{m.sender}</Text>
                <Text size="sm">{m.message}</Text>
                <Text size="xs" c="dimmed" ta="right">
                  {new Date(m.createdAt).toLocaleString()}
                </Text>
              </Paper>
            </div>
          ))}
        </Stack>
      </ScrollArea>
      <Group mt="sm" align="flex-end">
        <Textarea
          value={draft}
          onChange={e => setDraft(e.currentTarget.value)}
          onKeyDown={handleKeyDown}
          placeholder="Type a message… (Enter to send)"
          autosize minRows={1} maxRows={3}
          style={{ flex: 1 }}
        />
        <Button onClick={send} loading={sending}>Send</Button>
      </Group>
    </Paper>
  );
}

Using on a detail page#

<DiscussionThread
  entityType="Invoice"
  entityId={params.id!}
  currentUser={auth.getUser()}
/>

The same component works for any entity — just pass a different entityType / entityId.

Production error handling

Mon, 01 Jan 0001 00:00:00 +0000

Production error handling with PalmyraStoreFactory#

The default error handler in a fresh PalmyraStoreFactory does nothing — errors propagate to the component that triggered the call. In production you want a centralized handler that differentiates status codes, throttles toast spam, and routes auth failures to login.

The pattern#

// src/wire/StoreFactory.ts
import { PalmyraStoreFactory } from '@palmyralabs/palmyra-wire';
import { toast } from 'react-toastify';
import Swal from 'sweetalert2';

let lastServerErrorAt = 0;
const COOLDOWN_MS = 5000;

const errorHandler = () => (error: any) => {
  const status = error?.response?.status;

  switch (status) {
    case 401:
      // Session expired — redirect to login
      window.dispatchEvent(new CustomEvent('session:expired'));
      window.location.assign('/login');
      return true;

    case 403:
      // ACL denied
      toast.error("You don't have permission for this action.", { toastId: 'acl-403' });
      return true;

    case 400:
      // Validation error — show the server's message if available
      const msg = error?.response?.data?.message;
      toast.error(msg || 'Invalid request. Please check your input.', { toastId: 'val-400' });
      return true;

    case 500:
    case 503: {
      // Server error with cooldown — prevent toast spam when every grid/form fails at once
      const now = Date.now();
      if (now - lastServerErrorAt > COOLDOWN_MS) {
        toast.error('Server error. Please retry in a moment.');
        lastServerErrorAt = now;
      }
      return true;
    }

    case 502: {
      // Server down — show a modal instead of a toast (more prominent)
      Swal.fire({
        icon: 'warning',
        title: 'Server Unreachable',
        text: 'The server is currently unavailable. Please try again later.',
        confirmButtonText: 'OK',
      });
      return true;
    }

    default:
      // Unknown error — let it propagate to the component
      return false;
  }
};

const AppStoreFactory = new PalmyraStoreFactory({
  baseUrl: '/api',
  errorHandlerFactory: errorHandler,
});

export default AppStoreFactory;

What each status does#

Status	UX	Why this approach
401	Redirect to `/login`	Session is gone — no point showing a toast the user can’t act on
403	Toast with `toastId` (deduped)	Tell the user they lack permission; `toastId` prevents duplicate toasts if multiple calls fail simultaneously
400	Toast with server message	Server validation errors carry a meaningful `message` — show it
500 / 503	Toast with 5-second cooldown	When the server is struggling, every pending request fails — without cooldown you’d see 10 identical toasts
502	SweetAlert2 modal	Server is completely down — a modal is more visible than a toast and blocks further action

Listening for session expiry elsewhere#

// In your App or layout component
useEffect(() => {
  const handler = () => {
    // Clear local auth state, ACL cache, etc.
    localStorage.clear();
  };
  window.addEventListener('session:expired', handler);
  return () => window.removeEventListener('session:expired', handler);
}, []);

Install SweetAlert2#

npm install sweetalert2

Only needed for the 502 modal. If you prefer a Mantine Modal, replace the Swal.fire(...) call — the pattern is the same.

Advanced on Palmyra

Building filterable dashboards

Building filterable dashboards#

Architecture#

Shared filter context#

Filter bar#

Chart widget using ChartStore#

Summary cards#

Composing the dashboard page#

Key patterns#

Custom DataGridControls

Custom DataGridControls#

The contract#

A reusable toolbar#

Using it on a grid page#

Variant: popup grid controls#

File upload with drag-and-drop

File upload with drag-and-drop#

Install#

Reusable dropzone component#

Using it on a detail page#

Backend endpoint#

Workflow timeline visualization

Workflow timeline visualization#

Component#

Using it on a detail page#

Client-side Excel export

Client-side Excel export#

Install#

Export utility#

Using it from a grid toolbar#

When to use client-side vs. server-side export#

Frontend ACL with permission codes

Frontend ACL with permission codes#

Permission code config#

Dark/light theme switching

Dark/light theme switching#

Theme context#

Toggle button#

Wiring#

Multilingual support with i18n

Multilingual support with react-i18next#

Install#

Setup#

In-app discussion threads

In-app discussion threads#

Backend#

React chat component#

Using on a detail page#

Production error handling

Production error handling with PalmyraStoreFactory#

The pattern#

What each status does#

Listening for session expiry elsewhere#

Install SweetAlert2#