Object Type: Output Object
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
The name of the object.
Here a comment can be entered. For example a short description of the object.
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
- 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.