Working With Structured Data Types

Scenario:

1. Structured data types can be selected as a data type for a property in the same way as for the primitive data types, such as int, float, string, etc.
2. Structured data types can contain any number of data elements, each of which can be a primitive type, an array, or even another structure
3. The data elements are organized as name/value pairs, according to the JSON format
4. Arrays, data structures, and other types of data elements can be nested within a JSON data structure
5. We'll be creating a persistent “_settings” property for our “Thermometer” thing, which contains named values based on a new structured data type
6. The data structure will be defined with the following elements of data:
   • unitOfMeasure - string, accepts only "celsius" or "fahrenheit”
   • ledColor - string, accepts only "red", "green", or "blue"
7. A script property called “settings” will then be created to provide the logic for getting the current "_settings" property values or setting new ones if they are validated

Prerequisites:

1. A "Thermometer" thing was created in the Create, Read And Write Property scenario
2. All new "_settings" property values must be validated before storing as a persistent property
3. If any of the "_settings" property values don't match one of the acceptable strings, an error will be indicated
4. The UI or API can be used with the "settings" property to execute the code for getting/setting property values for “_settings” (with validation)

Steps: 

1. Creating a "ThermometerSettings" structured data type

---

1. Click "Data Types" in the main menu to open a tab listing the data types
2. Click "+" to open "Create Structure Type" dialog
3. Enter "ThermometerSettings" as the name for the new structured data type
4. Click "+" button to add the data elements to the data structure
5. Set the name of the first data element to "unitOfMeasure"
6. Check "Required" 
7. Select "string" in the drop-down menu as the data type for this element (clicking "..." opens the menu)
8. Click "+" button again
9. Set the name of the second data element to "ledColor"
10. Check "Required" 
11. Select "string" again in the drop-down menu as the data type for this element
12. Click "Save" to save the new structured data type

2. Creating a persistent "_settings" property

---

1. Open "Properties" in the "Thing: Thermometer" tab
2. Click "New" to open "Create Property" dialog
3. Enter "_settings" as the name for this property
4. Select "persistent" as the property type
5. To select "DataType", click the "..." button to open a drop-down menu
6. Click "more types" in this menu to open the "Select Type" dialog
7. Type "Therm" in the search field to locate the new structured data type
8. Select "ThermometerSettings" in the search results
9. Click "Select" to enter the new data type in the "Data Type" field
10. Check "Private" (property value in GK can only be set internally by methods or script property logic)
11. Save the new property

3. Creating a script "settings" property

---

1. Open "Properties"
2. Click to open "Create Property" dialog
3. Enter "settings" as the name for this property
4. Select "script" as the property type
5. Follow steps 5 - 9 of the previous section to select "ThermometerSettings" as "Data Type" for this property
6. Save the new property

4. Coding the get/setSettings script logic for "settings"

---

1. Open "Properties"
2. Select the new "settings" script property
3. Click to open "Edit Script" dialog

4. Insert the following JavaScript code for both getSettings( ) and setSettings( ) functions:
5. Save script by clicking "Save"

5. Get/set property values using UI

---

1. Select "Properties"
2. Select the "settings" script property
3. Click "Edit Value" to open a dialog

4. Insert the following code in the "Value" text area (values correspond with the new "ThermometerSettings" structured data type):
5. Click "Set" to retain the structured data values in the persistent memory locations for "_settings"
6. Click "Get" to retrieve the current "_settings" property values