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 (`ListGrid` 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 (eg `ListGrid.exportClientData()`):
  - if `exportAs` is a spreadsheet format (XLS or OOXML), rules are the same as for server-driven export except that `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 values to appear exactly as shown to the user, set `DSRequest.exportDatesAsFormattedString`, but see the docs for this property 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.
  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 (note, `exportValueFields` has no effect for server-driven exports):

  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 |  | ✓
  exportClientData(), valueMap defined in code, exportValueFields=true |  | ✓
  exportClientData(), valueMap defined in code, exportValueFields=false |  | ✓
  exportClientData(), optionDataSource, exportValueFields=true | ✓ | ✓
  exportClientData(), optionDataSource, exportValueFields=false |  | ✓
  exportData(), in-record displayField (must be declared in DataSource) | ✓ | ✓
  exportData(), valueMap declared in DataSource | ✓ |
  exportData(), valueMap defined in code | ✓ |
  exportData(), optionDataSource | ✓ |

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