Module: Editor
Version: 2.2.1 +
User: Developer
Object Type: Action Object
Description
XmlBuilders are used to construct XML. One XMLBuilder represents one XML element. Using multiple XMLBuilders a complete XML-tree can be constructed. The hierarchical structure of the XML-tree is formed by nesting these XMLBuilders in a specific order. Futurama objects like the Fixed, the Formula and the Reference can then be used to add attributes to the XML elements as well as to add elements containing a value.
A number of objects (DocConverter, WebService, WebReference and FileSaver) need an XMLBuilder as it's input. See the description of these objects for more information on how each of them makes use of the XMLBuilder.
An XMLBuilder is also used in combination with an XmlConverter. Using an XMLBuilder combined with an XMLConverter it is possible to generate HTML code with accompanying style elements.
Properties
Condition
This property indicates under which condition the XML element is to be constructed. If nothing is entered the XML element will always be constructed. If a condition has been filled in, the XML element will only be constructed if the Condition is 'True'. The condition can be a Fixed, a Formula or a Reference to another object of type Boolean. Note that if the XmlBuilder has a condition and is used as a loop to generate multiple XML elements, the condition will be verified before the loop will start. This means that if the condition is 'False' the entire loop is omitted. If a loop is to be constructed in which every step is depending on a condition then first an XMLBuilder has to be made containing the loop and inside it a second XMLBuilder containing the condition. Whether or not to construct the XML element of the second XMLBuilder is then determined in every step of the loop.
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
IgnoreChildErrors
This property is only visible when the property CalculationType of the Document is 'Standard'. With this property it is possible to choose what should happen when one of the elements of the XMLBuilder is invalid (i.e. NaN or Infinity). When 'IgnoreChildErrors' is set to 'True' the element in which the element occurred is included in the XML though without a value. When 'IgnoreChildErrors' is set to 'False' the whole element in which the error occurred is omitted from the constructed XML. See the paragraph 'IgnoreChildErrors property' for more information and a sample file.
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.
RepeatData
An XmlBuilder can create more than one XML element if it is defined as a loop. It can only refer to a UserTable, DataTable or Range. RepeatData contains a table with all the elements that need to be used in the loop. These elements are subsequently assigned to the UserVariable defined in the RepeatTarget property.
RepeatTarget
This property is used in conjunction with RepeatData. It can only refer to a UserVariable. The RepeatTarget property can be considered as the counter of a loop. During the execution of the loop it subsequently gets assigned all the values in the table defined in the RepeatData property.
XmlName
The name of the object as it is shown in the source of the website. By default the XmlName is equal to the name given in the property (Name) with spaces replaced by underscores, but you are free to change it.
(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.
Examples
Example 1
This example demonstrates the use of attributes and values.
Download
Download the Futurama Document xmlbuilder example1.
Description
- Open the XML-document which is contained in the zip-file in the Futurama Editor (Version 4.2.1 or later).
- The Document contains two XMLBuilders: "Data" and "Additional Data". Click on the XMLBuilder "Data". The constructed XML by this XMLBuilders can now be verified in the Results Window.
- The XMLBuilder "Data" contains a Fixed "Name" and a Formula "Salary". In the Results Window it can be verified that both are included as elements in the element "Data".
- In addition "Data" has an attribute ''@admin". Attributes can be recognized by the "@" in front of the name. In the Results Window it can be verified that the attribute admin has been added to the element "Data". Note that attributes always have to be placed before the normal elements.
- Finally a Reference is made to another XMLBuilder "Additional data". This XMLBuilder contains two elements: "Address" and "Town". Because the name of the Reference is preceded by a "$" the XMLBuilder it refers to will not be rendered itself but only it's underlying elements. This can be verified in the Results Window. The element "Data" doesn't contain the element "Additional data", but "Address" and "Town" instead.
- To see the difference, remove the "$" and verify the result again. It can be seen now that an element "Additional_data" is present, containing "Address" and "Town".
Example 2
This example demonstrates a loop in XMLBuilder.
Download
Download the Futurama Document xmlbuilder example2.
Description
- Open the XML-document which is contained in the zip-file in the Futurama Editor (Version 4.2.1 or later).
- In the Document an XMLBuilder "Loop" can be seen which is used to create a number of elements by means of a loop. The number of times that it is to run is defined by the number of elements in the table in the property RepeatData. This property refers to Range which consists of five elements. So the loop is run 5 times. Note that in the Futurama Editor, the results tab of the XMLBuilder “Test” will only show the outcome of the first 5 elements of the table defined in the property RepeatData of the XMLBuilder “Loop”, regardless on the actual amount of elements in the table.
- As counter the UserVariable 'Counter' is defined in the property RepeatTarget. During the loop 'Counter' will be assigned the value of each element in 'Range' subsequently.
- In "Loop" a Reference named "testvalue" is defined referring to "Counter". This implies that an element is created in the XML-data named "testvalue" which has the value of "Counter". It is therefore expected that after the loop is concluded five elements will have been created, all named "testvalue", but with values 1 to 5.
- Verify the result of the XMLBuilder "Test". It can be seen that it indeed contains five elements with values 1 to 5. Note that XMLBuilders which are designed for running a loop are not included in the XML-data themselves.
Example 3
In this example is shown how an XmlBuilder with error handling is created.
Download
Download the Futurama Document xmlbuilder example3.
Description
The property IgnoreChildErorrs can be used in combination with the formula CountErrors to add error handling to an XmlBuilder. This is useful when you want to add error handling to an XmlBuilder that is used for a WebService response. In the case that an error occurs then instead of an XML tree with an empty node, the node or the whole XML tree will be invisible. This is done with the property IgnoreChildErrors. In the XML tree there is also a message that says that there occurred an error. This is done with an extra XmlBuilder that depends on the formula CountErrors and inside the XmlBuilder a Fixed with the message ‘Error Occurred’.
In the example you can see an XmlBuilder that contains a loop and an XmlBuilder with the error handling. When you go and stand on ‘Output’ the XmlBuilder will be evaluated normally. But when you change the Fixed ‘Number’ to 0, and evaluate the Xmlbuilder ‘Output’ an error occurs. This is because the item with index 2 is divided by zero. Now you only see a node with the message ‘Error Occurred’. The ChangeValue in the XmlBuilder sets how many errors there are before the loop is executed. In the Condition parameter of the XmlBuilder ‘Error’ the error count is compared with the errors before. When the error count is higher the message ‘Error Occurred’ will be shown.
Notice that all nodes except the parent node is set to IgnoreChildErrors=False.
Relevant Tutorials
- Using XSLT to display data: This tutorial shows how the XMLBuilder is used in combination with an XMLConverter to display text on a website.
- Creating a Webservice Application: This tutorial shows how the XMLBuilder is used in combination with a WebService to create the WebServices output.
- Creating a Console Application: This tutorial shows how the XMLBuilder is used in combination with a DocConverter to export data to a Word document.