Rename scripts can add their own fields to the rename dialog itself, by implementing the OnGetCustomFields event. This lets you provide one or more controls that users can use to pass parameters to your script. Users can also feed parameters to your script using the SCRIPTARG argument for the Rename command.
Custom fields can use check boxes, string fields, number fields and drop-downs.
To add custom fields from your rename script, implement the OnGetCustomFields method. The above fields were added using the following code (in VBScript):
Function OnGetCustomFields(ByRef getFieldData)
' Add the custom fields
getFieldData.fields.my_option = True
getFieldData.fields.my_field = ""
getFieldData.fields.my_value = 20
getFieldData.fields.my_combo = DOpus.Create.Vector(1, "Option 1", "Option 2",
"Option 3")
' Assign labels to them
getFieldData.field_labels("my_field") = "My String Field"
getFieldData.field_labels("my_option") = "My Option"
getFieldData.field_labels("my_value") = "My Integer Value"
getFieldData.field_labels("my_combo") = "My Dropdown"
' Set cue text for the text field
getFieldData.field_tips("my_field") = "Enter your text here"
End Function
Custom fields are defined in much the same way as Script add-in defines its configuration using the ScriptConfig object. The OnGetCustomFields method is passed a GetCustomFieldData object. Fields are added by assigning properties of the GetCustomFieldData.fields object to the variable type you want the field to use (e.g. assign True or False for a Boolean, a string for a text string, etc.). The value you provide will become the default value for the field.
Each field can also have a label, and text fields can have a “cue banner” which is shown when the text field is empty (as seen above). Two Map objects are provided (GetCustomFieldData.field_labels and GetCustomFieldData.field_tips) which allow you to assign these.
The Rename dialog will expand automatically to accommodate your custom fields – obviously, screen space isn’t infinite, so you shouldn’t add too many fields or the dialog will grow too big for the screen!
The values that the user enters into your custom fields are provided to your OnGetNewName method via the CustomFieldData object passed as the GetNewNameData.custom. Each field you add in OnGetCustomFields will appear as a property of this object. For example, this function will print the provided values to the output log.
Function OnGetNewName(ByRef getNewNameData)
DOpus.Output "Option: " & getNewNameData.custom.my_option
DOpus.Output "String: " & getNewNameData.custom.my_field
DOpus.Output "Number: " & getNewNameData.custom.my_value
DOpus.Output "Dropdown: " & getNewNameData.custom.my_combo
OnGetNewName = True ' skip rename
End Function
When the user automates the Rename command to run your rename script directly (using the PRESET argument), they can use the SCRIPTARG parameter to pass data for your custom fields through. This argument accepts multiple name:value pairs. For example, assume the above script was saved as the rename preset “MyRename”. The user might run the following command:
Rename PRESET MyRename SCRIPTARG my_option:True my_field:moocow