Module: Editor
Version: 3.0.0 +
User: Developer
Object Type: Output Object
Description
A DocConverter object is used to produce Word or PDF documents. 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 Word and Adobe themselves are installed on the webserver. It is also possible to include graphs generated by the GraphConverter.
Behavior (from Futurama 18.02)
The behavior of DocConverter depends on the context it is defined in, and the mode Futurama is running in.
DocConverter placed within an XmlBuilder
If a DocConverter 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
DocConverter placed elsewhere
If a DocConverter 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
Properties
BrowserAction (from version 18.02)
BrowserAction indicates how the browser should handle the produced document. 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 DocConverter is to be executed. If nothing is entered the DocConverter will always be executed. If a condition has been filled in, the DocConverter 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 (from version 4.1)
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
DocumentFormat
This property can have the values 'Doc' or 'PDF'. If 'Doc' is chosen, the generated document will be a Word-document. If 'PDF' is chosen it will result in a PDF-document.
FileHandling (from version 18.02)
Possible values are SaveToFile and Auto. See the Behavior paragraph mentioned above. This property is only applicable when the DocConverter is not placed within an XmlBuilder.
ForceEvenPageCount (from version 4.2.0)
If this property is set to 'True' the generated document will always have an even number of pages. This implies that a blanc page will be added if the text ends on an odd page. The rationale behind this property is that for printing processes it is often desirable to always have an even number of pages.
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.
OpenMode (obsolete: Changed into BrowserAction in version 18.02)
This property can have the values 'OpenInBrowser' or 'OpenAsAttachment'. When 'OpenInBrowser' is chosen a PDF-document will be opened directly in a new window of the browser. If it is a Word-document a pop-up window will appear which offers the possibility to either save the document or to open it in Word. When 'OpenAsAttachment' is chosen a pop-up window offering the possibility to either save the document or to open it will appear for either format.
ResultFileName
This property contains the name of the document that will be generated. If the property 'DocumentFormat' is set to 'Doc', then the name has to have the extension .doc (Word will give an error when when you use .docx). If the property 'DocumentFormat' is set to 'PDF', the .pdf extention is not automatically added to the name. When DocConverter is used to generate documents in batch (see below) the full path has to be stated as well as the name. When DocConverter is used to open a document directly from a website, only the name of the document has to stated. The user who opens the document then can choose the location where the document has to be saved. When DocConverter is child of an XmlBuider, ResultFilename is not displayed and its value is not used. From Futurama version 18.02 it is also possible to define the texts within a ResourceDocument. See the page Text management and Multi-language.
TemplateFileName
This property contains the path to the template (a .doc, .docx or .dot 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 document. The value of an XML element can be included in the document by means of inserting a MergeField. The chosen fieldname for the MergeField has to be the same as the name of the XML element whose value has to be placed on the location of the MergeField. If a graph has to be included, the fieldname has to be the name of the XML element preceded by "Image:". From Futurama version 18.02 it is also possible to define the texts within a ResourceDocument. See the page Text management and Multi-language.
Note that if the template uses track changes, only accepted changes will be used. Non-accepted changes will be ignored.
UseNestedData (from version 4.2.0)
If this property is set to 'False' then the XmlBuilder to which is referred in the property XmlData (see below) is not allowed to have nested XmlBuilders. If set to 'True' this is allowed. See below for more information.
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.
(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.
IncludeFontsInPDF (until version 4.0.0)
This property indicates whether the fonts used in the template are included in the PDF itself. By default a number of fonts is supported in Adobe. If the template that is used contains fonts that are not supported by Adobe as well as not installed on the client computer, then a font that does exist, is chosen automatically. Because of this the generated PDF can differ from client to client and this creates a situation in which it is not known in advance how the PDF is shown for each user. Setting IncludeFontsInPDF to 'True' will ensure that every user will see the same PDF. A disadvantage of including fonts however, is that the PDF files will increase in size.
Note that only fonts can be included that are installed on the server on which Futurama runs. Therefore make sure that all fonts needed are indeed installed.
From version 4.0.0 onwards this property is not available anymore; fonts will always be included.
Examples
Example 1
In this example it is shown how a Word document is generated including data from an XmlBuilder.
Download
Download the files used for the docconverter example1.
Description
- For this example the directory C:\temp\ is used. Create this directory if it doesn't exist yet on your system.
- Copy the Word template and the XML document to C:\temp\.
- Open the XML document in the Futurama Editor (Version 4.2.1 or later).
- The Document contains two XMLBuilders and an Action which contains a DocConverter. See the XMLBuilder for more information about how to construct XmlData. Verify in the Results Window that the XMLBuilder Data has four elements with values.
- In the property 'DocumentFormat' of the DocConverter it can be seen that it produces a Word document and the property 'ResultFileName' it is stated that the name will be 'Document.doc' and it will be placed in the directory C:\temp\.
- In the property 'XmlData' a reference is made to the XmlBuilder 'Data' for the data.
- In the property 'TemplateFileName' the path to the Word template 'Template DocConverter Example1.doc' is given. Open this template in Word.
- In the template it can be seen that there are four MergeFields, one for each of the XML elements. Note that the names of the MergeFields match those of the XML elements. Close the Word template.
- In the Futurama Editor select the Action and do a rightclick. Select Debug|Execute.
- In the directory C:\temp\ the file Document.doc will appear. Open this document.
- Verify that the values of the XmlBuilder are indeed filled in on the correct locations.
- Note further that the document contains two pages although the template only has one. This is because the property 'ForceEvenPageCount' is set to 'True'.
Example 2
In this example the use of UseNestedData will be shown to generate a dynamic number of elements to the document.
Download
Download the files used for the docconverter example2.
Description
- For this example the directory C:\temp\ is used. Create this directory if it doesn't exist yet on your system.
- Copy the Word template and the XML document to C:\temp\.
- Open the XML document in the Futurama Editor (Version 4.2.1 or later).
- The Document contains an XMLBuilder 'Test' in which another XMLBuilder 'Loop' is placed and an Action which contains a DocConverter. See the XMLBuilder for more information about how to construct XmlData.
- The XMLBuilder 'Loop' defines the loop which generates a number of elements 'Rows' each containing the element 'testvalue' which has a value equal to the counter of the loop.
- Verify in the Results Window that the XMLBuilder Test has an element 'Caption' and five elements 'Rows'.
- In the property 'DocumentFormat' of the DocConverter it can be seen that it produces a PDF document.
- Note that the property UseNestedData now has been set to 'True'.
- In the property 'TemplateFileName' the path to the Word template 'Template DocConverter Example2.doc' is given. Open this template in Word.
- As described in the paragraph UseNestedData (see below) the first MergeField has to be TableStart:Test and the last MergeField is TableEnd:Test. The second MergeField is the Caption. Then to gain access to the testvalues of the loop the third MergeField is TableStart:Rows followed by the MergeField testvalue and TableEnd:Rows. The last MergeField is TableEnd:Test.
- Close the Word template.
- In the Futurama Editor select the Action and do a rightclick. Select Debug|Execute.
- In the directory C:\temp\ the file "Document with nested data.PDF" will appear. Open this document.
- Verify that below the caption the five values are placed.
Note that the above only holds for a webapplication. In case of a console application (which has no website) the correct resolution for printing the graph in a document can be filled in directly.
Relevant Tutorials
- Creating a Console Application : This tutorial shows how the DocConverter is used in combination with an XMLBuilder to export data to a Word document.