Null Value Support

Note: Null data values are not supported on the Windows Mobile platform.

This document refers to example HTML. You can see the example HTML by downloading the hybridapp_null_value.zip file and extracting the hybridapp_null_value.html file.

In the example, MessageValueCollection is referenced by var values = myDataMessage.getValues();” and myDataMessage is created in the onHybridAppLoad method.

A specific MessageValue is referenced by values.getData(string key). If you use the Hybrid App designer, the IDE manages keys for you but with JavaScript API, you have to implement key management in the code yourself.

This example follows the IDE style of giving each control an ID and using that as the key for data that will be used in that control:

<input class="right" type="number" id="Nullvaluetest_int_value2_attribKey" 
sup_allows_null="true" sup_valuechanged="false" onchange="inputChanged(this)"/>

So if you want the MessageValue object corresponding to that control:

var value = values.getData(“Nullvaluetest_int_value2_attribKey”);

Once you have the MessageValue object you can see if it is null with:

var isNull = value.getNullAttribute();

Null Values and HTML

HTML usually puts an empty string into a control if it is assigned a null value. If the control is not changed but you get the data from it for its MessageValue object, the MessageValue object will have an empty string as its value instead of NULL. This means the NullAttribute is not set properly unless you set it yourself.

When using null values, keep in mind that the contents of the control do not tell you whether it should be null. This can cause bad data on the server. Putting an empty string into a number type MessageValue can throw a formatting exception on the server, so when using JavaScript API, you are responsible for maintaining null values.

The Sample HTML

This section references the hybridapp_null_value.html file to show examples of how to implement null values.

Recognizing NULL values – The example uses the same techniques as an Hybrid App generated with the designer to keep track of data values, keys, controls and null-ness.
Controls that allow null have a special attribute that identifies it is okay to be NULL:
```
<input class="right" type="number" id="Nullvaluetest_int_value2_attribKey" 
sup_allows_null="true" sup_valuechanged="false" onchange="inputChanged(this)"/>
```
This example processes the incoming data message and checks control attributes for null friendliness and issues an alert message for a null value in the wrong place.
```
hwc.processDataMessage = function(incomingDataMessageValue, noUI, loading, fromActivationFlow, dataType)   
```

Handling input to NullValue controls – This example uses an event handler to recognize user input:
```
<input class="right" type="number" id="Nullvaluetest_int_value2_attribKey"
      sup_allows_null="true" sup_valuechanged="false"  onchange="inputChanged(this)" /> 
```
inputChanged uses another special attribute to indicate that the user has put something in the control and it is no longer null.

Setting a value to NULL – In the HTML example, setKeyValueNull and setControlValueNull show how to set a value to null while managing the control attributes and the MessageValue null attribute.

Sending data to the server – In the example HTML, doUpdate uses the getUpdatedValue method to set the right value in the newNVT object. getUpdatedValue checks the control attributes and the MessageValue null attribute to decide what to send to the server.

Creating data with null values – In the example HTML, doCreate and doCreate2 show two ways of creating a record with null values.