Futurama Logo

Welcome to the Futurama Support Site

The Futurama Support Site is the website where you can find Futurama and Futurama Vision documentation. If you have any questions about the support pages or if you want to provide us feedback please send us an e-mail.




Index DocConverter
Previous  |  Next

 1      About Futurama
 1.1        Version information
 1.2        Getting Started
 1.2.1          Futurama Website
 1.2.1.1            Behavior of Futurama regarding TimeOuts, Login and Logoff
 1.2.1.2            Replacing an existing Futurama Session
 1.2.2          Futurama Webservice
 1.2.2.1            warmUpDocuments
 1.2.3          Futurama Export
 1.3        Overview - Futurama Modules
 1.3.1          Overview - Futurama Accounts
 1.3.2          Overview - Futurama Server
 1.3.3          Overview - Futurama Monitor
 1.3.4          Overview - Futurama Insight
 1.3.5          Overview - Futurama Console
 1.3.6          Overview - Futurama Webservice
 1.4        Loadbalancing Futurama applications
 1.4.1          Getting the most out of Futurama Web using the Load-Balancer
 1.4.2          Application Request Routing
 1.5        Text management and Multi-language
 2      Installation – Configuration – Testing
 2.1        Installation - Futurama Website Edition
 2.1.1          Installation Futurama HTML
 2.1.2          Installation Futurama Monitor
 2.1.3          Installation Futurama Insight
 2.1.4          Installation Futurama Accounts
 2.1.5          Installation SAML2LoadBalancer
 2.2        Installation - Futurama Export Edition
 2.2.1          Installation Futurama Console
 2.2.2          Installation Futurama Server
 2.3        Installation - Futurama Webservice Edition
 2.3.1          Installation Futurama Webservice
 2.4        Installation Futurama Editor
 2.5        Configuration
 2.5.1          Configuration - Cache
 2.5.2          Configuration - Calculation
 2.5.3          Configuration - Debug
 2.5.4          Configuration - File manager
 2.5.5          Configuration - Fileproviders
 2.5.6          Configuration - Format
 2.5.7          Configuration - History
 2.5.8          Configuration - Identity Provider
 2.5.9          Configuration - Log
 2.5.10           Configuration - Mail
 2.5.11           Configuration - Mapping
 2.5.12           Configuration - Monitor
 2.5.13           Configuration - PlugIns
 2.5.14           Configuration - Rendering
 2.5.15           Configuration - ScenarioRecording
 2.5.16           Configuration - Security
 2.5.17           Configuration - Server
 2.5.18           Configuration - Vision
 2.5.19           Configuration - WebAPI
 2.6        Logging
 2.7        Troubleshooting
 2.8        Security - hardening
 3      Updating and file compatibility
 3.1        Updating Futurama - Compatibility behavior
 3.2        Converting Futurama documents
 3.3        12819 - DataTable file updates
 3.4        12889 - DataTable file updates
 3.5        Conversion web.config to .NET Framework 4
 3.6        Deprecated conversion formulas
 4      Futurama Editor - How to
 4.1        At first glance
 4.2        Developing in the Futurama Editor
 4.2.1          Working with objects
 4.2.2          Evaluating objects
 4.2.3          Finding objects
 4.3        Transferring objects
 4.4        Testing objects
 4.5        Validating objects
 4.6        Troubleshooting objects
 4.7        Advanced/special functionality
 4.8        Checking the layout of objects
 5      Futurama - Formulas
 5.1        Futurama Formulas - Date and time
 5.1.1          Date
 5.1.2          Day
 5.1.3          Days360
 5.1.4          Days360Excel
 5.1.5          DaysInMonth
 5.1.6          DaysInPeriod
 5.1.7          Min
 5.1.8          Max
 5.1.9          Month
 5.1.10           Now
 5.1.11           WeekDay
 5.1.12           Year
 5.2        Futurama Formulas - Math
 5.2.1          Abs
 5.2.2          Add
 5.2.3          Divide
 5.2.4          Floor
 5.2.5          Ln
 5.2.6          Log
 5.2.7          Log10
 5.2.8          Mod
 5.2.9          Multiply
 5.2.10           Pi
 5.2.11           Power
 5.2.12           Rand
 5.2.13           Round
 5.2.14           RoundDown
 5.2.15           RoundUp
 5.2.16           SquareRoot
 5.2.17           Subtract
 5.3        Futurama Formulas - Statistical
 5.3.1          AverageDeviation
 5.3.2          Beta
 5.3.3          Binomial
 5.3.4          Covariance
 5.3.5          Factorial
 5.3.6          Gamma
 5.3.7          GeometricMean
 5.3.8          Lognormal
 5.3.9          Max
 5.3.10           Median
 5.3.11           Min
 5.3.12           Normal
 5.3.13           StandardDeviation
 5.3.14           Uniform
 5.3.15           Variance
 5.4        Futurama Formulas - Text
 5.4.1          CalculateBase64Hashcode
 5.4.2          CalculateXmlHashcode
 5.4.3          Concatenate
 5.4.4          ConcatenateBase64
 5.4.5          ContainsText
 5.4.6          Convert.CSV.2.XML
 5.4.7          ConvertFromBase64
 5.4.8          ConvertToBase64
 5.4.9          ConvertXml
 5.4.10           DecodeURL
 5.4.11           DecryptXml
 5.4.12           EncodeURL
 5.4.13           EncryptXml
 5.4.14           Find
 5.4.15           HashBase64EncodedFile
 5.4.16           HashBase64EncodedFileWithBase64
 5.4.17           HashText
 5.4.18           HashTextWithBase64
 5.4.19           Left
 5.4.20           Len
 5.4.21           Linefeed
 5.4.22           Lower
 5.4.23           Mid
 5.4.24           Proper
 5.4.25           ReadConfigKey
 5.4.26           ReadDirectoryNames
 5.4.27           ReadFile
 5.4.28           ReadFileAsBase64
 5.4.29           ReadFileNames
 5.4.30           ReadFileWithEncoding
 5.4.31           ReadXPathScalar
 5.4.32           ReadXPathVector
 5.4.33           Repeat
 5.4.34           Right
 5.4.35           Substitute
 5.4.36           Trim
 5.4.37           TrimLeft
 5.4.38           TrimRight
 5.4.39           Upper
 5.4.40           ValidatePattern
 5.4.41           XsdMessages
 5.5        Futurama Formulas - Logical
 5.5.1          And
 5.5.2          IsEmpty
 5.5.3          If
 5.5.4          IsEqual
 5.5.5          IsEven
 5.5.6          IsGreater
 5.5.7          IsGreaterEqual
 5.5.8          IsIBANChecksumValid
 5.5.9          IsLess
 5.5.10           IsLessEqual
 5.5.11           IsMemberOfGroup
 5.5.12           IsNotEqual
 5.5.13           IsOdd
 5.5.14           IsValidXml
 5.5.15           Not
 5.5.16           Or
 5.5.17           ValidateNPR
 5.6        Futurama Formulas - Table
 5.6.1          FindNextRow
 5.6.2          FindPreviousRow
 5.6.3          FindRow
 5.6.4          Sort
 5.6.5          VLookUp
 5.7        Futurama Formulas - Document
 5.7.1          CountErrors
 5.7.2          GetPathToDataFiles
 5.7.3          GetPortNumber
 5.7.4          GetRelativePathToDataFiles
 5.7.5          GetSessionID
 5.7.6          IsLicenceAvailable
 5.7.7          ReadError
 5.7.8          ReadIdentityProviderResult
 5.7.9          ReadRequestIP
 5.7.10           ReadRequestParameter
 5.7.11           ReadUserAgent
 5.7.12           ReadVersionNumber
 5.7.13           SessionTimeOut
 5.7.14           URL
 5.7.15           UserName
 5.8        Futurama Formulas - Conversion
 5.8.1          Convert.Excel.to.XML
 5.8.2          ConvertJSONtoXml
 5.8.3          ConvertTextToDate
 5.8.4          ConvertTextToNumber
 5.8.5          ConvertToBoolean
 5.8.6          ConvertToDouble
 5.8.7          ConvertToLong
 5.8.8          ConvertToString
 5.8.9          FormatDate
 5.8.10           FormatNumber
 5.8.11           Value
 5.9        Futurama Formulas - Matrix
 5.9.1          AddMatrices
 5.9.2          AddScalarToMatrix
 5.9.3          Cumulative
 5.9.4          CumulativeProductMatrix
 5.9.5          Distinct
 5.9.6          DivideMatrices
 5.9.7          DivideMatrixScalar
 5.9.8          DivideScalarMatrix
 5.9.9          Exponent
 5.9.10           First
 5.9.11           Floor
 5.9.12           If
 5.9.13           Index
 5.9.14           Inverse
 5.9.15           IsEqual
 5.9.16           IsGreater
 5.9.17           IsGreaterEqual
 5.9.18           IsNotEqual
 5.9.19           IsLess
 5.9.20           IsLessEqual
 5.9.21           Join
 5.9.22           Last
 5.9.23           Length
 5.9.24           MatrixProduct
 5.9.25           Max
 5.9.26           MaxScalarMatrix
 5.9.27           Mean
 5.9.28           Mid
 5.9.29           Min
 5.9.30           MinScalarMatrix
 5.9.31           MultiplyMatrices
 5.9.32           MultiplyMatrixVector
 5.9.33           MultiplyScalarMatrix
 5.9.34           Percentile
 5.9.35           PowerMatrix
 5.9.36           PowerMatrixScalar
 5.9.37           PowerScalarMatrix
 5.9.38           ReadMatrixFromXml
 5.9.39           Repeat
 5.9.40           Replace
 5.9.41           Reshape
 5.9.42           ReverseCumulativeProductMatrix
 5.9.43           ReverseMatrix
 5.9.44           Size
 5.9.45           Split
 5.9.46           SquareRootMatrix
 5.9.47           Step
 5.9.48           SubtractMatrices
 5.9.49           SubtractMatrixScalar
 5.9.50           SubtractScalarMatrix
 5.9.51           Sum
 5.9.52           Transpose
 5.9.53           UnitMatrix
 5.9.54           Vector
 5.10         Creating custom formulas in Futurama
 6      Futurama - Objects
 6.1        Action
 6.2        Aggregation
 6.3        Button
 6.4        ChangeValue
 6.5        CheckBox
 6.6        ClearCache
 6.7        DatabaseField
 6.8        DatabaseView
 6.9        DataTable
 6.10         DateBox
 6.11         DocConverter
 6.12         Document
 6.13         Download
 6.14         DropDownList
 6.15         EmailConverter
 6.16         ExcelConverter
 6.17         FileSaver
 6.18         FileUploader
 6.19         Fixed
 6.20         Formula
 6.21         GraphConverter
 6.22         HTMLInclude
 6.23         InterfacesNode
 6.24         LogMessage
 6.25         Navigator
 6.26         Node
 6.27         RadioButton
 6.28         RadioGroup
 6.29         Range
 6.30         Reference
 6.31         SubDocument
 6.32         TextBox
 6.33         UserTable
 6.34         UserVariable
 6.35         WebLabel
 6.36         WebListBox
 6.37         WebPage
 6.38         WebPanel
 6.39         WebReference
 6.39.1           WebReference - WCF Configuration
 6.40         WebService
 6.41         WebSlider
 6.42         WordConverter
 6.43         XmlBuilder
 6.44         XmlConverter
 6.45         XmlField
 6.46         XmlNode
 7      Futurama - Vision References
 7.1        Data
 7.1.1          ReadData
 7.1.2          WriteMessage
 7.1.3          GetPersonIdentifiers
 7.1.4          CreatePerson
 7.2        DataStore
 7.2.1          DeleteDataItem
 7.2.2          DeleteDataItemHierarchy
 7.2.3          DeleteDataItems
 7.2.4          GetDataItem
 7.2.5          GetDataItemHierarchy
 7.2.6          GetDataItems
 7.2.7          StoreData
 7.3        Accounts
 7.3.1          Activate Account
 7.3.2          Change Account
 7.3.3          Create Account
 7.3.4          GetQuestion
 7.3.5          GetQuestions
 7.3.6          Login
 7.3.7          ReadData
 7.3.8          ReinitializeAccount
 7.4        General
 7.4.1          TestConnection
 8      Futurama Vision
 8.1        Installation Futurama Vision
 8.1.1          Installation Futurama Vision Management Site
 8.1.2          Installation or Upgrade of the Futurama Vision Database
 8.2        Futurama Vision Management Site
 8.2.1          Futurama Vision Management Site - Admin
 8.2.2          Futurama Vision Management Site – Security
 8.2.3          Futurama Vision Management Site – Skinning
 8.2.4          Importing data into Futurama Vision
 8.2.4.1            Importing data by webservice
 8.2.4.2            Importing data from a Zip-file
 8.2.4.3            Importing data with Futurama Vision Batch
 8.2.4.4            Futurama Vision Webservice Security
 8.2.5          Further processing of data into Futurama Vision
 8.3        Futurama Vision File manager
 8.4        Activity overview
 8.5        Storing data in Vision from a Futurama application
 8.6        Futurama Vision – Data
 8.7        Futurama Accounts - Management Site
 8.7.1          Futurama Accounts - Table in Vision Database
 8.8        Futurama Server - Management Site
 8.8.1          Special Futurama Server Jobs
 8.9        Futurama Register - Management Site
 8.9.1          Configuration - Futurama Register
 8.10         Retrieving AppEvents from Futurama Vision
 8.11         Adding CustomPages to Vision
 9      Futurama Intermediate Control Output (FICO)
 9.1        FICO example - Change/Add HTML headers
 9.2        FICO example - Change Graph
 9.3        HTML5 Template
 10       Futurama Web API
 10.1         Postbacks of Futurama webcontrols
 10.2         Retrieving Resources using Web API
 10.3         WebAPI Session management
 11       Tutorials - Overview
 11.1         Tutorials - Examples and Downloads
 11.2         Beginners
 11.2.1           Creating formulas with Futurama
 11.2.1.1             Exercise 1: Pythagorean Theorem (Easy)
 11.2.1.2             Exercise 2: Newspaper stall (Medium)
 11.2.1.3             Exercise 3: Recursive functions (Difficult)
 11.2.1.4             Exercise 4: Leap Year (Difficult)
 11.2.1.5             Exercise 5: The Guessing Game I (Medium)
 11.2.2           Creating a Website Application
 11.2.2.1             Exercise 1: Creating a Website (Easy)
 11.2.3           Styling your website with CSS
 11.2.3.1             Exercise 1: Adding CSS (Easy)
 11.2.4           Adding interactivity to your website
 11.2.4.1             Exercise 1: Summation (Easy)
 11.2.4.2             Exercise 2: The Guessing Game II (Medium)
 11.2.4.3             Exercise 3: Nationality (Medium)
 11.2.4.4             Exercise 4: Nationality - RepeatTarget (Medium)
 11.2.4.5             Exercise 5: Reversed Guessing (Difficult)
 11.2.5           Working with Tables
 11.2.5.1             Exercise 1: Average (Easy)
 11.2.5.2             Exercise 2: Boundary values (Difficult)
 11.2.5.3             Exercise 3: Standard Deviation (Medium)
 11.2.6           Reading and processing XML-data in Futurama
 11.2.6.1             Exercise 1: Shares (Medium)
 11.2.7           Adding Graphs in Futurama
 11.2.7.1             Exercise 1: World Population (Easy)
 11.2.8           Working with Actions in Futurama
 11.2.8.1             Exercise 1: Changing Colors (Easy)
 11.2.8.2             Exercise 2: On and Off (Medium)
 11.2.8.3             Exercise 3: The ChangeValue object (Difficult)
 11.2.8.4             Exercise 4: The Guessing Game III (Medium)
 11.2.8.5             Exercise 5: CheckBox (Medium)
 11.2.9           Multiple Pages and Navigation
 11.2.10            Using XSLT to display data
 11.2.10.1              Exercise 1: Overview Summation (Easy)
 11.2.10.2              Exercise 2: Persons (Medium)
 11.2.10.3              Exercise 3: Leap Year Overview (Difficult)
 11.2.11            Webservices in Futurama
 11.2.11.1              Exercise 1: Example (Easy)
 11.2.12            Creating a Webservice Application
 11.2.12.1              Exercise 1: Add (Easy)
 11.2.12.2              Exercise 2: Webservice Nationality (Medium)
 11.2.13            Creating a Console Application
 11.2.13.1              Exercise 1: Adding extra fields (Easy)
 11.2.14            Generating Documents
 11.2.14.1              Exercise 1: Tax Rate (Medium)
 11.2.14.2              Exercise 2: Tax Rates Table (Difficult)
 11.3         Advanced
 11.3.1           Responsive Design
 11.3.1.1             Exercise 1: Orientation
 11.3.1.2             Exercise 2: Target different screen sizes
 11.4         Older Tutorials (Futurama Version 3.2)
 11.4.1           Futurama Editor Tutorial 1: The first sum
 11.4.2           Futurama Editor Tutorial 2: An annuity
 11.4.3           Futurama Editor Tutorial 3: Working with tables
 11.4.4           Futurama Editor Tutorial 4: Modelling a DB pension plan
 11.4.5           Futurama Editor Tutorial 5: Working with XML
 11.4.6           Futurama Web Tutorial 1: Hello world
 11.4.7           Futurama Web Tutorial 2: Buttons and Actions
 11.4.8           Futurama Web Tutorial 3: Textboxes
 11.4.9           Futurama Web Tutorial 4: DropdownLists
 12       Miscellaneous
 12.1         Responsive website
 12.2         Reducing memory usage for XmlNodes and XmlFields
 12.3         Explaining caching for websites and webservices
 12.4         Certificates - basic information
 12.5         Performance XML operations
 12.6         Creating XSD files and using them in combination with Futurama
 13       Templates
 14       Safe2Save WebAPI Sample
View  |  Print  |  PDF

451 documents found.


DocConverter

Developer
Futurama-Objects
Futurama-Editor
Output-Objects

Module: Editor

Version: 3.0.0 +

User: Developer

Object Type: Output Object

Parent of:

no children

Child of:

- Action

- Document

- Node

- XmlBuilder

 

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.

Conditional text

Using the DocConverter it is possible to show text in the template conditionally. This is useful if multiple different documents will be generated using only one template. This template then can contain all possible text and during generating the individual documents it is determined by a condition whether or not to actually include the text.

In order to include conditional text a couple of steps have to be taken in the template and in the Editor:

  1. In the template select the text that is to be shown conditionally;
  2. Next select Insert | Bookmark and give the bookmark an appropriate name;
  3. In the Futurama Editor define an object of type Boolean (Formula, Reference, Fixed etc.) in the XMLBuilder that is referred to in the XmlData property of the DocConverter;
  4. Give the object the same name as the bookmark;

When the document is generated and this Boolean is 'True', the conditional text belonging to the accompanying bookmark will be shown. If the Boolean is 'False', the text will be omitted.

UseNestedData

Using UseNestedData it is possible to include certain information multiple times in a template. In the Editor the XMLBuilder that is used as the input for the DocConverter will then have a nested XmlBuilder containing a loop. See Example 2 of the XMLBuilder object to see how such a loop is constructed.

In the template a number of steps have to be taken:

  • Before the first MergeField in the document a special MergeField has to be included with the name "TableStart:<xxx>". <xxx> is here the name of the XmlBuilder to which is referred in the property 'XmlData'.
  • After the last MergeField in the document another special MergeField has to be included with the name "TableEnd:<xxx>".

Example 2 shows a simple example of the use of nested data. A more telling example can be found here.

Including a document in an XML message

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

Resolution of graphs

When a graph, that is shown clear on screen, is printed in a document it often results in a graph that is not sharp any more. In order to overcome this the resolution of the graph has to be enlarged. However when raising the resolution of a graph while keeping the size of the graph (height and width) the same number of pixels, this will result in a graph that is smaller. The reason for this is that the resolution is defined in dots (i.e. pixels) per inch (dpi). If the number of dots per inch (i.e. the resolution) increases but the total number of dots remains the same, the number of inches will decrease. The graph will thus become smaller. By increasing the resolution as well as the number of pixels, the size of the printed graph can be maintained while it will be sharper at the same time. There are no fixed rules for resolution and number of pixels. Establishing which resolution and number of pixels produces the desired result therefore requires a bit of trial-and-error.

Once the desired resolution and number of pixels for the width and height has been determined, a couple of steps have to be taken to implement this in Futurama:

  • In the XMLBuilder that has a reference to the GraphConverter an Action has to be declared before the Reference to the GraphConverter.
  • This Action has to target the GraphConverter and change the properties "Height", "Width" and "Resolution" to the desired values. See Example 1 of the Action object to see how an Action can change the properties of another object.
  • After the reference to the GraphConverter another Action has to be placed in order to return the properties "Height", "Width" and "Resolution" to the original values. If this is omitted then the GraphConverter will keep it's new values and these will also be used when showing the graph on screen. This will have a guaranteed undesired result!

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.

Generating documents in batch

Using a DocConverter 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 DocConverter in a batch process the name in the property ResultFileName has to contain the name and path.

Related Topics

- XMLBuilder

- Action

- GraphConverter

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.

Updated: 2017-01-23


Previous  |  Next