Skip to main content

Exporting DataSets

FdcExporter.exportDataSet is the canonical API for exporting rows directly from an FdcDataSet.

final result = await FdcExporter.exportDataSet(
  orders,
  format: FdcExportFormat.json,
  options: FdcExportOptions(
    scope: FdcExportScope.currentView,
    valueMode: FdcExportValueMode.raw,
  ),
  suggestedFileName: 'orders.json',
);

Row scopes​

FdcExportScope determines which dataset rows are materialized before serialization.

ScopeMeaning
allRowsAll non-deleted dataset rows, ignoring the current filter, sort, and search view
currentViewRows in the current dataset view, respecting filter, sort, and search state
selectedRowsSelected rows from the current dataset view
currentRowOnly the current row; empty when there is no current record
changedRowsPending inserted, updated, and deleted rows from dataSet.changeSet

For most user-triggered exports, currentView is the safest default because the generated file matches the data context the user is currently working with.

FdcExportOptions(
  scope: FdcExportScope.selectedRows,
)

changedRows is useful for diagnostics, audit previews, and custom synchronization workflows. Its row order is inserts, then updates, then deletes.

Raw versus display values​

FdcExportOptions(
  valueMode: FdcExportValueMode.raw,
)

raw preserves typed scalar values where the writer supports them. Non-native FDC value objects are converted to stable textual representations when required by the target format.

FdcExportOptions(
  valueMode: FdcExportValueMode.display,
)

display converts values to presentation-oriented text before writing. Use it when the exported representation should favor what users see over preserving type information.

For grid exports, visible grid columns can also provide value formatters so presentation writers such as PDF preserve column display formatting more precisely.

Column resolution​

When columns is empty, the exporter infers columns from dataset field definitions:

FdcExportOptions()

By default, inferred columns include persistent fields only. Include calculated or other non-persistent fields explicitly:

FdcExportOptions(
  includeNonPersistentFields: true,
)

Or provide an explicit ordered export schema:

FdcExportOptions(
  columns: const [
    FdcExportColumn(
      fieldName: 'order_no',
      key: 'orderNumber',
      label: 'Order number',
    ),
    FdcExportColumn(
      fieldName: 'total',
      label: 'Total',
      textAlignment: FdcExportTextAlignment.right,
    ),
  ],
)

FdcExportColumn separates source identity from output presentation:

  • fieldName resolves the source value,
  • key controls object-oriented output identity where applicable,
  • label supplies tabular headers,
  • valueFormatter supplies presentation text,
  • textAlignment is a hint for presentation writers.

Headers​

FdcExportOptions(
  includeHeaders: false,
)

includeHeaders applies to formats that have a header concept, including CSV, Excel SpreadsheetML, and PDF tables.

CSV options​

FdcExportOptions(
  csvDelimiter: ';',
  lineTerminator: '\r\n',
)

The CSV delimiter must be non-empty and cannot contain quotes or line breaks. Valid line terminators are \n, \r\n, and \r.

Spreadsheet-like text beginning with =, +, -, or @ is sanitized by default to reduce formula-injection risk:

FdcExportOptions(
  sanitizeSpreadsheetFormulas: true,
)

Only disable this for trusted data when the downstream spreadsheet behavior is intentional.

XML options​

FdcExportOptions(
  rootElementName: 'orders',
  rowElementName: 'order',
)

Both names must be valid simple XML element names and must not begin with xml.

Exporting already resolved rows​

Use FdcExporter.exportRows when another source has already materialized the exact rows and columns:

final result = await FdcExporter.exportRows(
  format: FdcExportFormat.csv,
  columns: const [
    FdcExportColumn(fieldName: 'code', label: 'Code'),
    FdcExportColumn(fieldName: 'name', label: 'Name'),
  ],
  rows: rows,
);

This API is useful for custom report projections, grid-derived shapes, and non-dataset sources while still reusing the same writer registry.

Result handling​

final bytes = result.bytes;
final maybeText = result.textOrNull;

if (maybeText != null) {
  // Text format such as CSV, JSON, XML, or SpreadsheetML.
} else {
  // Binary format such as PDF.
}

Metadata is available through:

  • result.format,
  • result.mimeType,
  • result.fileExtension,
  • result.suggestedFileName.