Method: Workbook#compatibility_mode

Defined in:

lib/writeexcel/workbook.rb

#compatibility_mode(mode = true) ⇒ Object

Set the compatibility mode.

This method is used to improve compatibility with third party applications that read Excel files.

workbook.compatibility_mode

An Excel file is comprised of binary records that describe properties of a spreadsheet. Excel is reasonably liberal about this and, outside of a core subset, it doesn’t require every possible record to be present when it reads a file. This is also true of Gnumeric and OpenOffice.Org Calc.

WriteExcel takes advantage of this fact to omit some records in order to minimise the amount of data stored in memory and to simplify and speed up the writing of files. However, some third party applications that read Excel files often expect certain records to be present. In “compatibility mode” WriteExcel writes these records and tries to be as close to an Excel generated file as possible.

Applications that require compatibility_mode() are Apache POI, Apple Numbers, and Quickoffice on Nokia, Palm and other devices. You should also use compatibility_mode() if your Excel file will be used as an external data source by another Excel file.

If you encounter other situations that require compatibility_mode(), please let me know.

It should be noted that compatibility_mode() requires additional data to be stored in memory and additional processing. This incurs a memory and speed penalty and may not be suitable for very large files (>20MB).

You must call compatibility_mode() before calling add_worksheet().

Excel doesn’t require every possible Biff record to be present in a file. In particular if the indexing records INDEX, ROW and DBCELL aren’t present it just ignores the fact and reads the cells anyway. This is also true of the EXTSST record. Gnumeric and OOo also take this approach. This allows WriteExcel to ignore these records in order to minimise the amount of data stored in memory. However, other third party applications that read Excel files often expect these records to be present. In “compatibility mode” WriteExcel writes these records and tries to be as close to an Excel generated file as possible.

This requires additional data to be stored in memory until the file is about to be written. This incurs a memory and speed penalty and may not be suitable for very large files.

# File 'lib/writeexcel/workbook.rb', line 440

def compatibility_mode(mode = true)
  unless sheets.empty?
    raise "compatibility_mode() must be called before add_worksheet()"
  end
  @compatibility = mode
end