Versioning for custom properties


Custom properties don’t have built-in support for versioning. After you create an instance of a property, the Define callback is never called again. So if you update your custom property with new parameters, you won’t see those new parameters in existing instances of the property.

If you want to support versioning, you can build it into the OnInit callback.

Add a Version parameter to the custom property. Then in the OnInit, you can compare this Version parameter against the current version of the custom property. If the property was created by an older version of the plugin, then you can update the property by adding parameters or by calling EditParameterDefinition to modify an existing parameter. But you cannot cannot remove parameters (instead, hide them).

If you have custom properties that don’t a Version parameter, then the most you can do is check for the existence of the Version parameter. If it is not there, then you know the property is older and needs to be updated.

Finally, you need to rebuild the PPG layout whenever OnInit is called. The typical way to do this is to get rid of the DefineLayout function and implement your own “RebuildLayout” function.

Here’s an example plugin that shows how to update an existing instance of a property:

var gCURRENT_VERSION=1.2;
function XSILoadPlugin( in_reg )
{
	in_reg.Author = "blairs";
	in_reg.Name = "MyPropertyPlugin";
	in_reg.Major = 1;
	in_reg.Minor = 2;

	in_reg.RegisterProperty("MyProperty");
	//RegistrationInsertionPoint - do not remove this line

	return true;
}

function XSIUnloadPlugin( in_reg )
{
	var strPluginName;
	strPluginName = in_reg.Name;
	Application.LogMessage(strPluginName + " has been unloaded.",siVerbose);
	return true;
}

function MyProperty_Define( in_ctxt )
{
	var oCustomProperty;
	oCustomProperty = in_ctxt.Source;
	oCustomProperty.AddParameter2("Version",siDouble,gCURRENT_VERSION,0,100,0,100,0,siPersistable+siNotInspectable);
	// Version 1.0
	oCustomProperty.AddParameter2("Param",siInt4,0,0,100,0,100,siClassifUnknown,siPersistable | siKeyable);
	// Version 1.1
	oCustomProperty.AddParameter2("NewParam",siInt4,0,0,100,0,100,siClassifUnknown,siPersistable | siKeyable);
	// Version 1.2
	oCustomProperty.AddParameter2("Flag",siBool,true,null,null,null,null,siClassifUnknown,siPersistable | siKeyable);
	return true;
}

function MyProperty_RebuildLayout()
{
	var oLayout = PPG.PPGLayout ;
	var oItem;
	oLayout.Clear();
	oLayout.AddItem("Param");
	oLayout.AddItem("NewParam");
	oLayout.AddItem("Flag");
	return true;
}

function MyProperty_OnInit( )
{
	Application.LogMessage("MyProperty_OnInit called",siVerbose);


	oEnum = new Enumerator( PPG.Inspected ) ;
	for (;!oEnum.atEnd();oEnum.moveNext() )
	{
		var oCustomProperty = oEnum.item() ;
		updateParameters( oCustomProperty );
	}

	MyProperty_RebuildLayout();
	PPG.Refresh();	
}

function updateParameters( oCustomProperty )
{
	var oVersion = oCustomProperty.Parameters.Item("Version");
	var propertyVersion = ( oVersion == null ) ? 0.0 : oVersion.Value;

	if ( propertyVersion < gCURRENT_VERSION )
	{
		LogMessage( "Updating " + oCustomProperty.FullName + " to version " + gCURRENT_VERSION );

		//------------------------------------------------------
		// Update parameter definitions
		//------------------------------------------------------

		var oParameter = oCustomProperty.Parameters.Item("Param");

		// Min, Max, SuggestedMin, SuggestedMax are read-only
		// So use EditParameterDefinition to update those settings
		if ( propertyVersion < 1.1 )
		{
			// Update the SuggestedMax
			EditParameterDefinition( oParameter, "", 0, 0,100,0,10, "", "" );
		}
		
		//------------------------------------------------------
		// Add new parameters
		//------------------------------------------------------

		if ( oCustomProperty.Parameters.Item( "NewParam" ) == null )
		{
			oCustomProperty.AddParameter2("NewParam",siString,"Cool!",null,null,null,null,0,siPersistable);
		}

		if ( oCustomProperty.Parameters.Item( "Flag" ) == null )
		{
			oCustomProperty.AddParameter2("Flag",siBool,true,null,null,null,null,siClassifUnknown,siPersistable | siKeyable);
		}
		//------------------------------------------------------
		// Update Version parameter
		//------------------------------------------------------
	
		if ( oVersion == null )
		{
			oVersion = oCustomProperty.AddParameter2("Version",siDouble,1.0,0,100,0,100,0,siPersistable+siNotInspectable);
		}
		oVersion.Value = gCURRENT_VERSION;
	}
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s