Accessing Templated User Data on Components

Templated user data also uses the binary user data map, but offers more built-in functionality and interactive tools. The plug-in developer creates a user data template, which is similar to an empty parameter set, and specifies what kinds of data can be attached to the map.

The developer then associates this template with a user data map (also through scripting). The template allows a user to easily view, set, and edit the user data in the map through the user interface.

Note

Once the template has been built and associated to a particular user data map, and users have begun to associate values, you should not add or remove parameters.

For this reason, you should consider user data templates to be Read-Only.

VBScript Example: Creating a user data template

The first part of this procedure consists of creating the template, which is the same as creating a custom parameter set:

' Create a grid 
Set oRoot = ActiveSceneRoot
Set oGrid = oRoot.AddGeometry( "Grid", "MeshSurface" )

' Create a custom parameter set
aCls = Array( 27,28,35,36 )
Set oCluster = oGrid.ActivePrimitive.Geometry.AddCluster( siPolygonCluster,, _
						aCls )
Set oParamSet = oCluster.AddProperty( "Custom_parameter_list")

oParamSet.AddParameter "Juiciness_Factor", siFloat,,,,,, 25, 0, 50
oParamSet.AddParameter "Special_Instructions", siString
oParamSet.AddParameter "Toggle_Effect", siBool,,,,,, True

Note

You can create the template either through scripting or through the user interface. For instructions on creating custom parameter sets through the user interface, see the Animation guide.

The result of this script is a template that looks like this:

The next step is to create a user data map through scripting and associate the new template to it.

' Attach a user data map to a cluster on the grid
Set oUDMap = oCluster.AddProperty( "UserDataMap" )

' Associate the template to the new user data map
Set oUDMap.Template = oParamSet

Once this association is made, you can provide user interaction through a parameter dialog box.
```
' Change some values on selected clusters
Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
		siPolygonCluster, aCls )
SIInspectUserData oUDMap, oSubComp
```
The following message is logged to the History Log of the Script Editor:
```
'SIInspectUserData "grid1.polymsh.cls.Polygon.User_Data_Map", "grid1.poly[27,28,35,36]"
```
Note
SIInspectUserData is a scripting command, so if you are planning to use it in a compiled plug-in, you will need to use the XSIApplication.ExecuteScriptCommand method. At this time, there is no equivalent functionality in the object model.
You can see any changes made to these values have been updated by running the OMView tool (see NetviewToolsInfo OM) while the user data map is selected.

Alternatively, you can access information about the values stored on the user data map by using the UserDataMap.ItemValue property. For more information, see VBScript Example: Getting user data on specific elements.

VBScript Example: Getting user data on specific elements

Follow the steps under VBScript Example: Creating a user data template to create and modify templated user data.
```
Call printInfo( oUDMap )

function printInfo( in_oUDMap )
```
Use the UserDataMap.Template property to get the template.
```
Set oTemplate = in_oUDMap.Template
```
Use the UserDataMap.Item property to get the user data on each individual cluster element as a UserDataItem object.

Tip
You should test each item to see whether it contains data, since the whole user data map may be associated to a cluster with a lot of unused elements.
```
	For iCounter = 0 to in_oUDMap.Count - 1
		LogMessage "========================================================="
		LogMessage "Information for Point #" & (iCounter + 1)
		LogMessage "---------------------------------------------------------"
		If (Not oUDMap.IsEmpty(iCounter)) Then
			Set oUDItem = in_oUDMap.Item(iCounter)
			oTemplate.BinaryData = oUDItem.Value
```
Note
Using the UserDataItem object is the equivalent to using the UserDataMap.ItemValue property. For an example using the UserDataMap.ItemValue property, see VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue.

Iterate over each parameter in the template to get its value (each piece of user data can be accessed as a user data map template parameter).

	
			For Each oParam in oTemplate.Parameters
				If oParam.Value = "" Then
					LogMessage oParam.ScriptName & ": (no data)"
				Else
					LogMessage oParam.ScriptName & ": " & oParam.Value
				End If
			Next
		End If
	Next

	LogMessage "========================================================="
end function

The following message is logged to the History Log of the Script Editor:

'INFO : "========================================================="
'INFO : "Information for Point #1"
'INFO : "---------------------------------------------------------"
'INFO : "Juiciness_Factor: 25"
'INFO : "Special_Instructions: (no data)"
'INFO : "Toggle_Effect: True"
'INFO : "========================================================="
'INFO : "Information for Point #2"
'INFO : "---------------------------------------------------------"
'INFO : "Juiciness_Factor: 25"
'INFO : "Special_Instructions: (no data)"
'INFO : "Toggle_Effect: True"
'INFO : "========================================================="
'INFO : "Information for Point #3"
'INFO : "---------------------------------------------------------"
'INFO : "Juiciness_Factor: 25"
'INFO : "Special_Instructions: (no data)"
'INFO : "Toggle_Effect: True"
'INFO : "========================================================="
'INFO : "Information for Point #4"
'INFO : "---------------------------------------------------------"
'INFO : "Juiciness_Factor: 25"
'INFO : "Special_Instructions: (no data)"
'INFO : "Toggle_Effect: True"
'INFO : "========================================================="

Tip

Notice how that the information for each cluster element (user data item) displayed is the same. That is because the user data on all subcomponents in the cluster is being inspected:

	Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
			siPolygonCluster, aCls )
	SIInspectUserData oUDMap, oSubComp

If you want to change the data on individual elements, you can either use the UserDataMap.ItemValue property for each cluster element (see VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue) or use the SIInspectUserData command on a SubComponent that is derived from a single component of the cluster:

	Set oSubComp = oGrid.ActivePrimitive.Geometry.CreateSubComponent( _
			siPolygonCluster, array(27) )
	SIInspectUserData oUDMap, oSubComp

VBScript Example: Setting user data on specific elements with UserDataMap.ItemValue

Follow the steps under VBScript Example: Creating a user data template to create and modify templated user data.

' Change the values on some individual points
Call setValues( oUDMap, 0, 12, "Generic", False )
Call setValues( oUDMap, 1, 7, "Low", False )
Call setValues( oUDMap, 2, 23, "Severus", True )

You can access each parameter of the templated data through the Template property on the UserDataMap object:

sub setValues( in_objUDM, in_intID, in_strPar1, in_strPar2, in_strPar3 )
	' Assign the specified values to the individual parameters of the template
	in_objUDM.Template.Parameters("Juiciness_Factor").Value = in_strPar1
	in_objUDM.Template.Parameters("Special_Instructions").Value = in_strPar2
	in_objUDM.Template.Parameters("Toggle_Effect").Value = in_strPar3

Even though you have updated the templated data attached to the user data map, you still need to save those values back to the user data map in order for them to take effect. To save it to a specific point, use the matching UserDataMap.ItemValue property:
```
' Assign the template values back to the user data map
in_objUDM.ItemValue(in_intID) = in_objUDM.Template.BinaryData
end sub
```
Note
Using the UserDataMap.ItemValue property is the equivalent to using the UserDataItem object. For an example using the UserDataItem object, see VBScript Example: Getting user data on specific elements.