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(), DSRequest.getExportRawValues(), DSRequest.getExportPropertyIdentifier(), DSRequest.getExportDatesAsFormattedString(), DSRequest.getExportTZ(), FormItem.getExportFormat(), SimpleType.getFormat(), SimpleType.getExportFormat(), DetailViewerField.getFormat(), DetailViewerField.getExportFormat(), ListGridField.getFormat(), ListGridField.getExportFormat()