Record PDF Export

Record PDF Export turns a single Docyrus data source record into a PDF through a guided three-step wizard:

1. Select a Template — lists the data source's saved HTML/PDF templates (tenant_html_template).
2. Preview — renders the chosen template compiled against the record, using the HtmlTemplateEditor in preview-only mode.
3. PDF — generates the final PDF server-side and shows it in an inline viewer with a download button.
4. Email (optional, when sendEmail is set) — mounts an email composer (useDocyrusEmailComposer) with the generated PDF pre-attached, so the user can send the record straight from the wizard.

The headless useDocyrusRecordPdfExport hook owns all data fetching, step state, and PDF generation. DocyrusRecordPdfExportWizard is the batteries-included UI built on top of it. The hook accepts a dataSourceId and recordId — the app / data source slugs needed by the render endpoints are resolved automatically (or supplied explicitly).

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-record-pdf-export

pnpm add @tanstack/react-query @docyrus/api-client

Usage

Wizard inside a dialog

import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';
import { DocyrusRecordPdfExportWizard } from '@docyrus/ui/components/record-pdf-export';
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogTrigger
} from '@docyrus/ui/primitives/ui/dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';

function ExportRecordButton({ dataSourceId, recordId }: { dataSourceId: string; recordId: string }) {
  const { client } = useDocyrusAuth();
  const [open, setOpen] = useState(false);

  if (!client) return null;

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger asChild>
        <Button variant="outline">Export to PDF</Button>
      </DialogTrigger>
      <DialogContent className="max-w-4xl">
        <DialogHeader>
          <DialogTitle>Export record to PDF</DialogTitle>
        </DialogHeader>
        <DocyrusRecordPdfExportWizard
          client={client}
          dataSourceId={dataSourceId}
          recordId={recordId}
          onClose={() => setOpen(false)}
        />
      </DialogContent>
    </Dialog>
  );
}

Editable-template mode

Pass templateEditable to let the user tweak the rendered document before exporting. The preview step then exposes the Code, Data (read-only reference), and Preview tabs — the Code tab holds the server-compiled document HTML for this record. When it is edited, the PDF step renders the edited HTML through the custom-body endpoint instead of the saved template.

<DocyrusRecordPdfExportWizard
  client={client}
  dataSourceId={dataSourceId}
  recordId={recordId}
  templateEditable
/>

Email step

Pass sendEmail to append an Email step. After the PDF is generated, the wizard mounts an email composer (via useDocyrusEmailComposer) with the rendered PDF pre-attached (sent through its storage path) and the user's email accounts loaded into the From selector. Sending requires the Messaging.Email.Send OAuth scope.

<DocyrusRecordPdfExportWizard
  client={client}
  dataSourceId={dataSourceId}
  recordId={recordId}
  sendEmail
/>

Headless — drive your own UI

import { HtmlTemplateEditor } from '@docyrus/ui/components/html-template-editor';
import { useDocyrusRecordPdfExport } from '@docyrus/ui/components/record-pdf-export';

function CustomExport({ client, dataSourceId, recordId }) {
  const {
    step, goNext, goBack, canGoNext,
    templates, selectedTemplateId, setSelectedTemplateId,
    previewEditorProps,
    pdfUrl, isGeneratingPdf
  } = useDocyrusRecordPdfExport({ client, dataSourceId, recordId });

  // Step 1 — render `templates` and call `setSelectedTemplateId(id)`.
  // Step 2 — <HtmlTemplateEditor {...previewEditorProps} />
  // Step 3 — <iframe src={pdfUrl} /> (auto-generated on entering the step).
}

How it works

Preview uses the HTML Template Editor

The preview step mounts HtmlTemplateEditor with the server-compiled document HTML as value, then restricts the visible tabs. Compiling on the server (rather than client-compiling the raw template against the raw record) is what makes the preview faithful — the record's fields are mapped/expanded exactly as they are for the PDF. Three editor props power this:

In editable mode the user tweaks the compiled document HTML (the final output for this record) in the Code tab — the custom-body PDF endpoint takes final HTML as-is, so this is the only round-trip-faithful editing surface the API supports.

Hook — useDocyrusRecordPdfExport

const wizard = useDocyrusRecordPdfExport(options);

Options

Returns

API Reference — DocyrusRecordPdfExportWizard

Extends every hook option plus:

Type Exports