Search

Module: Editor

Version: 18.11+

User: Developer

Object Type: Output Object

Parent of:

no children

Child of:

- Action

- Document

- Node

- XmlBuilder

Description

An ExcelConverter object is used to produce Excel workbooks. These documents can be either stored to a filesystem, be opened in a webpage or incorporated inside an XML message. In order to do this it is not needed that Excel itself is installed on the webserver.

Behavior

The behavior of ExcelConverter depends on the context it is defined in, and the mode Futurama is running in.

ExcelConverter placed within an XmlBuilder

If an ExcelConverter is placed in an XmlBuilder, it will always convert the file contents to a base64 string and embed it in the xml that is generated by the XmlBuilder

ExcelConverter placed elsewhere

If an ExcelConverter is placed elsewhere, the FileHandling property is used to specify the behavior:

  • If FileHandling=SaveToFile, the file will always be saved to the location as specified in ResultFileName
  • If FileHandling=Auto, the behavior will depend on the mode Futurama is running in. If this is not Website mode, the file will be saved to the location as specified in ResultFileName. If this is Website mode, the BrowserAction property is used. If BrowserAction=Open, the file will be opened in the client browser window. If BrowserAction=Download, the file will be offered as a download in the client browser

Note that the Excel workbooks are generated/merged without the use of Microsoft Excel itself. It is therefore not necessary to install Microsoft Excel on the Futurama server. On the other side, Excel formulas (if present) will not be evaluated immediately when the workbook is generated, but only after the workbook is opened in Microsoft Excel.

Properties

BrowserAction

BrowserAction indicates how the browser should handle the produced workbook. This property only works when ‘Filehandling’ is set to ‘Auto’ and the Futurama process runs in Website mode. The possible values of BrowserAction are ‘Open’ or ‘Download’. If BrowserAction=Open, the file will be opened in the client browser window. If BrowserAction=Download, the file will be offered as a download in the client  browser.

Condition

This property indicates under which condition the ExcelConverter is to be executed. If nothing is entered the ExcelConverter will always be executed. If a condition has been filled in, the ExcelConverter will only be executed if the Condition is 'True'. The condition can be a Fixed, a Formula or a Reference to another object of type Boolean.

DebugLogMode

Indicates the level of detail of debug information that is logged when running a Futurama application (website, webservice, console application) to the trace, a logfile, a database etc. The possible values are:

  • None: no debug information is logged
  • Simple: only basic information is given
  • Extended: in addition to the information in the Simple mode the values of all the properties of the object are shown

FileHandling

Possible values  are SaveToFile and Auto. See the Behavior paragraph mentioned above. This property is only applicable when the ExcelConverter is not placed within an XmlBuilder.

IsPublic

Possible values are 'True' or 'False'. If the value is 'False', then the object can only be used within the document where it is created. If the value is 'True', then also from other Futurama documents can be referred to this object. This means that changes in the object also affect the document in which is referred to this object. If the value is 'True' and you attempt to move or delete the object, a warning will be given. To limit these warnings to a minimum it is recommended to set IsPublic to 'True' only when necessary.

ResultFileName

This property contains the name of the workbook that will be generated. this ResultFileName can either have extension .xls or .xlsx, independent of the extension that is used in TemplateFileName. When ExcelConverter is used to generate documents in batch (see below) the full path has to be stated as well as the name. When ExcelConverter is used to open a workbook directly from a website, only the name of the workbook has to be stated. The user who opens the workbook then can choose the location where the workbook has to be saved. When ExcelConverter is child of an XmlBuider, ResultFilename is not displayed and its value is not used.

TemplateFileName

This property contains the path to the template (a .xls, .xlsx or .xls file) that is to be used to generate the documents. The XmlData combined with the template will make sure the correct data is placed in the correct place in the workbook. The value of an XML element can be included in the workbook by means of inserting a named range. The chosen range name has to be the same as the name of the XML element whose value has to be placed on its location.

Visible

Possible values are 'True' or 'False'. If the value is 'True', the object will be rendered and therefore displayed in your application. If the value is 'False', the object will not be rendered.

XmlData

In this property a reference has to be made to the XmlBuilder that contains the data that is to be included into the document. In the template indicated in the property TemplateFileName it can then be declared where every element has to be placed. XmlData can have scalars, vectors or matrices in its root node. These elements will be placed in the cell with the range names that correspond to the xml element names. For vectors and matrices, the complete set will be added, started at the first column and row of the named range. It is also possible to add an integer ‘R’ and/or ‘C’ attribute in the xml structure. By using these, you can ‘move’ to a different row or column (starting at the named range). R=’1’ C=’2’ will enter the data 2 columns right and 1 row below the named range.

(Name)

The name of the object.

Comment

Here a comment can be entered. For example a short description of the object.

ID

The unique identification number of the object. This number is automatically generated by Futurama on the moment of creation. This number can be used when searching for a certain object in the Find Window.

Including a document in an XML message

As stated before an ExcelConverter is used to produce documents which can be stored to disc or be opened in a webpage. It is also possible to include a workbook in an XML message. It will then be represented by a Base64 string. In order to accomplish this, the ExcelConverter itself has to be placed inside the XMLBuilder which is used to generate the XML message. Including a Reference to an ExcelConverter will not work.

Generating documents in batch

Using a ExcelConverter in combination with a batchfile it is possible to generate a (large) number of documents and store these to file. The ResultFileName property will then contain a Formula to generate an unique name for every document. See for an example of how to do this the tutorial Creating a Console Application.

Note that when using the ExcelConverter in a batch process the name in the property ResultFileName has to contain the name and path.

Example

In this example it is shown how an Excel workbook is generated including data from an XmlBuilder.

Download

Download the files used for the excelconverter example1.

Description

  • Open the Futurama document in the Futurama Editor (Version 18.11 or later).
  • The Document contains an Action which contains a ExcelConverter. See the XMLBuilder for more information about how to construct XmlData. Verify in the Results Window that the XMLBuilder Data has several elements with values. These are scalar elements, a vector with dates and a matrix with double values. In addition, the ‘Salary’  node contains attributes R=0 and C=1 to move 1 column to the right.
  • In the property 'ResultFileName' it is stated that the name will be spreadsheet.xlsx' and it will be placed in the subdirectory ‘output’.
  • In the property 'XmlData' a reference is made to the XmlBuilder 'Data' for the data.
  • In the property 'TemplateFileName' the path to the Excel template 'template\Template ExcelConverter Example 1.xls' is given. Open this template in MS Excel.
  • In the template it can be seen that there are 7 named ranges, one for each of the XML elements. Note that the names of the ranges match those of the XML elements. Close the Excel template.
  • In the Futurama Editor select the Action and do a rightclick. Select Debug|Execute.
  • In the subdirectory output the file spreadsheet.xlsx will appear. Open this workbook.
  • Verify that the values of the XmlBuilder are indeed filled in on the correct locations.

Related Topics

- XMLBuilder

- Action

Relevant Tutorials

- Creating a Console Application : This tutorial shows how a DocConverter is used in combination with an XMLBuilder to export data to a Word document. This is equivalent to creating Excel workbooks.

Updated: 2018-10-24