Edition: Futurama Website/Futurama Export/Futurama Webservice
Module: Futurama Editor
Validating is a very useful tool to quickly check whether the objects in the Futurama Document are properly defined. Unlike errors Validation messages can be considered more as warnings or recommendations than as flaws which need to be addressed. There are many types of Validation messages. Many are related to specific types of objects. A number of frequently occuring Validation messages will be discussed here.
Performing a validation
Any object can be validated. When an object is validated which contains other objects then these will be validated as well automatically. To validate an object perform the following steps:
- Select the object that has to be validated in either the Document Explorer or the Design window.
- Do a right click.
- Select Debug | Validate.
In the Validation Window any validation messages will now appear. The name of the object concerned is shown in the column "Item", the validation message is shown in the column "Message". In addition, checkmarks will appear in the Document Explorer; every object that is validated and 'approved' (i.e. it is properly defined) will obtain a green mark while every object that is not validated correctly will obtain a red cross. In this way it is quickly to see which objects need attention. Note that if a child of an object is invalid, the parent will also be designated as invalid.
To remove the checkmarks of an object (and its children) select the object followed by a right click. In the menu select Debug | Clear Validation. The checkmarks will now disappear.
An alternative way of getting the Validation Message of an object is by selecting an object followed by a right click and then selecting Debug | Get Validation Message. The message will then appear in a popup window.
In the Validation Window the messages can be removed by doing a right click and selecting Clear in the menu. Any message can also be copied for later use by hovering over a message, doing a right click and selecting Copy to clipboard.
Common validation messages
The following list contains a number of frequently occuring validation messages. Every message will be explained briefly.
- VersionNumber property cannot be Null: This message only applies to Documents. It means that the property VersionNumber has no value. As stated there it is not required to have set a version number but it is recommended to do so.
- Possible circular reference detected: This message applies to Formulas. It indicates that a Formula refers to itself directly or is part of a group of objects that form a circle. Creating a circular reference is allowed in Futurama, but because an unintentional circular reference can produce obscure results this message is very useful. See below for an example.
- This document uses CalculationType 'Compatibility' It is recommended to upgrade to 'Standard'. See help for more information: This message applies to the property CalculationType of Documents. It is recommended to use the CalculationType "Standard" for it assures that calculations are not executed when (part of) its input is invalid. This prevents the creation of erroneous results.
- Target is in another document and is not public: This message is relevant when working with SubDocuments. When referring to an object that is located in a SubDocument, this object has to be Public. If this is not the case Futurama will ask "Target is not public, do you want to make it public?" upon creating the reference. After this is confirmed, the reference can be made. Suppose in a later stage the referred object is, accidentally, made private once more. When validating the object which refers to this, now private, object, the message will appear. To solve this simply make the object Public again.
- Method Add must have result type long instead of double: This message applies to Formulas of type Double. When creating a Formula of this type it is also valid to select a Formula that results in a value of type Integer. Hence, the result is an integer, while the Formula should return a Double. This is valid in Futurama, for Integers are in fact just a subset of Doubles, but the message will appear. Note that Add is only one of the many methods that can result in this message.
Ignoring validation messages
Validation messages can be ignored through the context menu on the message itself. Ignored messages are stored on the Document (property ValidationMessagesToIgnore), and they can be un-ignored there.
In this example a Futurama Document is used containing two Formulas which are part of a circular reference. The document can be downloaded here. For this example Futurama 184.108.40.206 or later is required.
- Open the Futurama Editor.
- Open the document validation.xml.
- Select the Document 'Validation'.
- Do a right click and select Debug | Validate.
In the Validation Window three messages will appear. The first will state that the Document has no VersionNumber. The second and third indicate that objects B and C are part of a circular reference. Upon examining the two objects this indeed turns out to be true for B is defined as A + C, while C is defined as 4 + B. Note that the message that objects are part of a circular reference does not result in a red cross, for a circular reference is a valid construction in Futurama.
If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.