Package com.smartgwt.client.docs

# Interface ExportFormatting

public interface ExportFormatting

### Exports & Formatting

This topic explains the default rules for whether date, numeric and other formatting settings are applied when performing various types of exports, and how to override the default behavior.

For server-based exports (e.g. `ListGrid.exportData()` or `DataSource.exportData()`):

- if `exportAs` is a spreadsheet format (XLS or OOXML), `dsField.format` or `dsField.exportFormat` will be used if specified, otherwise, `DataSourceField.dateFormatter` will be used if specified, otherwise, no formatting will be applied and the date or number will be shown in the spreadsheet program's default formatting.
- if targetting CSV, XML or JSON, by default, formatting declarations are ignored and standard formats are used, because the expectation is that this type of export is intended for data interchange with other systems and not for direct viewing by end users. Specifically, date and datetime values use standard XML Schema date and time formats and CSV export uses the "yyyy-MM-dd HH:mm:ss" expected by Microsoft Excel and similar tools that consume CSV, with only the date or time part of the format being used for fields that are of type "date" or "time" rather than "datetime". If you instead set `DSRequest.exportRawValues` to false, format settings available to server will be used, exactly as explained above for spreadsheet exports with `exportData()`.

For a client-driven export (e.g. `ListGrid.exportClientData()` or `DataSource.exportClientData()`:

- if `exportAs` is a spreadsheet format (XLS or OOXML), rules are the same as for server-driven export, except that if no `dsField.format` or `dsField.exportFormat` is specified, `dateFormatter` settings on client-side UI components will be used if a built-in formatter is used (for example, if `ListGridField.dateFormatter` is set to the built-in formatter "toEuropeanShortDate"). If you need date or number values to appear exactly as shown to the user, set `DSRequest.exportDatesAsFormattedString` or `DSRequest.exportNumbersAsFormattedString`, respectively, but see the docs for these properties for the drawbacks of doing this.
- for CSV, XML or JSON exports, whatever is shown to the end user is used (since it's assumed the reason for calling `exportClientData()` rather than `exportData()` is precisely to create a fully formatted export). If you instead set `ListGrid.exportRawValues` to true, only standard formats appropriate to data interchange are used, the same as described for `exportData()` above.

These different default behaviors for different export formats can be overriden by use of `ListGrid.exportRawValues`. If you only want to override the default behaviors for numeric values, you can use `ListGrid.exportRawNumbers` (note, the `exportRawNumbers` setting has no effect if `exportRawValues` is set to true)

Use `DSRequest.exportPropertyIdentifier` to override the default behavior for a server or client-driven export and force either component field names or titles to be exported.

### Display-mapped fields

Smart GWT supports a number of ways to declaratively map underlying data values to "display values" that have more meaning to a user. This mapping can be achieved using a `displayField` in the same record, a `com.smartgwt.client.types.ValueMap` or an `optionDataSource`. The table below shows what values get exported for each of these possibilities, in combination with the `exportValueFields` flag and whether you are using client-driven or server-driven export:

Use case | Exports value field | Exports display field
exportClientData(), in-record displayField, exportValueFields=true | ✓ | ✓
exportClientData(), in-record displayField, exportValueFields=false |  | ✓
exportClientData(), valueMap declared in DataSource, exportValueFields=true |  | ✓
exportClientData(), valueMap declared in DataSource, exportValueFields=false |  | &#x2713
exportClientData(), valueMap defined in code, exportValueFields=true |  | ✓
exportClientData(), valueMap defined in code, exportValueFields=false |  | &#x2713
exportClientData(), optionDataSource, exportValueFields=true | ✓ | ✓
exportClientData(), optionDataSource, exportValueFields=false |  | ✓
exportData(), in-record displayField (must be declared in DataSource), exportValueFields not specified | &#x2713 | &#x2713
exportData(), in-record displayField (must be declared in DataSource), exportValueFields=true | &#x2713 |
exportData(), in-record displayField (must be declared in DataSource), exportValueFields=false |  | &#x2713
exportData(), valueMap declared in DataSource | ✓ |
exportData(), valueMap defined in code | ✓ |
exportData(), optionDataSource | ✓ |

See Also:
  - `CubeGrid.getValueFormat()`
  - `CubeGrid.getValueExportFormat()`
  - `SimpleType.getFormat()`
  - `SimpleType.getExportFormat()`
  - `DSRequest.getExportRawValues()`
  - `DSRequest.getExportPropertyIdentifier()`
  - `DSRequest.getExportDatesAsFormattedString()`
  - `DSRequest.getExportNumbersAsFormattedString()`
  - `DSRequest.getExportTZ()`
  - `FormItem.getExportFormat()`
  - `DetailViewerField.getFormat()`
  - `DetailViewerField.getExportFormat()`
  - `ListGridField.getFormat()`
  - `ListGridField.getExportFormat()`