Search

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.

IgnoreChildErrors property

With the IgnoreChildErrors property it can be decided how to deal with invalid elements in the XML tree constructed with an XMLBuilder. Frequently the XMLBuilder is used to construct an XML tree with a large amount of data. For example when one XMLBuilder is created with information for all your users. When for one of your users an invalid value occurs you probably only want information of the user where the invalid value occurs instead of stopping the whole process. This example is worked out in a sample document in order to make the IgnoreChildErrors property clear and to give an example how to display information about errors that may occur.

Download

Download the Futurama Document ignorechilderrors_example.

Description

In the sample an XMLBuilder is constructed with information regarding 4 users. For each of these users XML is constructed with an element Value. For user 2 an invalid value is constructed (by dividing by zero).

In the XMLBuilder 'Output IgnoreChildErrors False' the XMLBuilder 'User' is constructed. The 'IgnoreChildProperty' for this XMLBuilder is set to 'False'. When checking the result of the XMLBuilder 'Output IgnoreChildErrors False' you can see that the XML for user 2 in entirely omitted in the XML tree. See the XMLBuilder 'Output IgnoreChildErrors True' for the difference. In this XMLBuilder the property 'IgnoreChildErrors' is set to 'True' for the XMLBuilder 'User'. In this situation the XML for User 2 is shown, with an empty value for 'Value'.

Testfiles

The XML-data that is generated by an XmlBuilder can be tested in the Editor by creating a testfile. In the menuitem Tools|Settings in the menubar in the Editor the option 'TestFileNameXmlBuilder' can be used to indicate the name and location of this testfile. Therefore the extension always has to be 'xml'. In the Document Explorer a rightclick on the XmlBuilder opens a contextmenu. In this menu select the option Debug|Create Testfile. On the location specified in the option 'TestFileNameXmlBuilder' an XML-file is created containing the constructed XML-data. In this way it can be tested whether the structure and contents of the data is as expected.

Generating XSD files (Futurama 17.11+)

From Futurama 17.11 onward it is possible to generate a custom WSDL instead of the ‘generic’ WSDL. See Installation Futurama Webservice for more information. When modeling a custom WSDL the definition of the Request and Response of the webservice are laid down in a so called XSD file. In general an XSD file (XML Schema Definition) is a file that defines validation rules for XML, in this case the (XML) format of the Request and the Response. Constructing an XSD is not covered in the Futurama Support Site, for much information is available on the internet. However, to accommodate the construction of an XSD file, Futurama Editor contains functionality to generate a basic XSD file. In order to do this, perform a rightclick on the object and select Debug | Create xsd file. Futurama will open a Save As dialog window where the name and location of the XSD file can be specified. The generated XSD file only provides the basic structure. In order to make it work properly for the webservice under development it will need further alterations.

Attributes and values of an XmlBuilder

In an XmlBuilder objects can be placed with any name and value. These will be converted to elements in the XML-data. It is also possible to add attributes to an element. To do this simply define an object with the name and value of the attribute, but have the name preceding by the "@" symbol. This indicates that the object has to be transformed to an attribute instead of an element. Multiple attributes can be defined this way, but it's important that in an XMLbuilder first all attributes are defined before any other elements.

It is possible to include the value of an object directly in the XML-data without including the object itself as an element. This is done by having the name of the object be preceded by the "$" symbol. This is particularly useful when an XMLBuilder contains References to other XMLBuilders in order to retrieve their underlying. In this case it is often desired that only the elements of the other XMLBuilder are included rather than the XMLBuilder itself as well.

See Example 1 for a more extensive explanation of how to use the "@" and "$" symbols.

Loops

It is possible to create multiple elements in the XML-data through the use of a loop in the XMLBuilder. For this the properties RepeatData and RepeatTarget are used, analogous to the Action object. Example 2 shows how a simple loop is defined to create multiple elements.

Examples

Example 1

This example demonstrates the use of attributes and values.

Download

Download the Futurama Document xmlbuilder example1.

Description

  1. Open the XML-document which is contained in the zip-file in the Futurama Editor (Version 4.2.1 or later).
  2. 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.
  3. 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".
  4. 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.
  5. 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.
  6. 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

  1. Open the XML-document which is contained in the zip-file in the Futurama Editor (Version 4.2.1 or later).
  2. 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.
  3. 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.
  4. 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.
  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.

Updated: 2012-07-24