External property editor

Introduction

Switch supports a property editor called "External editor" that offers integrated editing capabilities for third-party property sets (such as a Preflight Profile) without including third-party code in Switch. The property set must be stored in a file, and an external editing application must be supplied that behaves according to some specific guidelines.

Designing a flow with an external property editor

When a user invokes an external property editor while designing a flow, Switch launches the associated external application and passes the file path to a copy of the property set to be edited. The external application brings up a dialog for editing the contents of the property set and saves any changes back into the file. When the application exits, Switch recognizes the updated property set.

The value of a property edited with the "External editor" property editor is a file path. The actual file is stored in a temporary place allocated by Switch (similar to property sets created while importing a flow).

The "External editor" property editor works well in conjunction with the "Choose file" property editor, since both operate on a file path. Furthermore, Switch always makes a copy of the property set before editing. This means that:

A property set that was selected with the "Choose file" property editor is never changed.
Edited property sets are never shared between multiple flow elements.

Specifying an external property editor in SwitchScripter

The "External editor" property editor supports the following extra properties (shown in SwitchScripter and stored in the script declaration):

Property	Description
Application	The path (absolute or relative) to the application (executable) used to edit a property set. If you want to dynamically specify the path to the External editor, you have to leave the value of this property empty and implement the findExternalEditorPath entry point in your script. If a relative path is specified (that is, the path does not start with a drive letter or a forward slash), Switch looks for the external application relative to the system Applications folder. Typically this is the "Program Files" folder (on Windows) or the "Applications" folder (on Mac). If no path is specified, Switch executes the findExternalEditorPath entry point and the returned path is considered the absolute path to the required editor application.
Arguments for new	The argument string passed to the application when there is no pre-existing property set, after substituting all occurrences of %1 and %2 as described below.
Arguments for edit	The argument string passed to the application when there is a pre-existing property set to be edited, after substituting all occurrences of %1 and %2 as described below.
Editor name	The name your external editor user will see when he will use the editor.
Value overlay	The value of this property defines the string that will be shown after the editor is closed. The default value for this property is 'External properties defined'.
File format	There are two values possible: If you want to use your own file format, choose Custom. If you want to use a format that Switch can understand, choose Switch. In that case, the XML must have the following format: <SwitchExternalEditor> <PathsForExport> <Path>c:/MyAppConfig/MyICCProfile.icc</Path> <Path>c:/MyAppConfig/MyKeyFile</Path> <Path>c:/MyAppConfig/MyOwnConfigurationFile.xml</Path> <Path>c:/AnotherFile</Path> </PathsForExport> </SwitchExternalEditor> The XML includes a list of file paths. The files listed in these <Path> tags will be exported within flows.

Note: If the file format is set to 'custom', Switch doesn't read the content of the property set and the files listed in the property set will not be exported within flows.

Substitutions in argument strings

The following substitutions are performed in the specified argument strings:

Placeholder	Replaced by
%1	The file path for the property set: If it points to an existing file, the external application should load this file and replace it by the updated property set (the "edit" argument string is used) If the path does not point to a file, the external application should place the newly created property set at this path (the "new" argument string is used)
%2	The locale currently in use by Switch specified as a four-letter string consisting of the two-letter ISO 639 language code (lowercase), followed by the two-letter ISO 3166 country code (uppercase); example: "enUS"

Placeholder

Replaced by

%1

The file path for the property set:

If it points to an existing file, the external application should load this file and replace it by the updated property set (the "edit" argument string is used)
If the path does not point to a file, the external application should place the newly created property set at this path (the "new" argument string is used)

%2

The locale currently in use by Switch specified as a four-letter string consisting of the two-letter ISO 639 language code (lowercase), followed by the two-letter ISO 3166 country code (uppercase); example: "enUS"

External application behavior

The external application must open the property set specified on its command line (or create a new default property set) and display a main window and/or a dialog box. After the user saves or cancels the changes, the application must exit with an appropriate exit code as follows:

Exit code	Meaning	Switch action
Zero	Changes to the property set were successfully saved	Use the newly created or updated property set
Nonzero	The user cancelled the operation or an error occurred	Discard any changes

Note: In case of the Switch file format, the external application must save a property set in the format described above (in the last row in the table under Specifying an external property editor in SwitchScripter).

Entry point example "findExternalEditorPath"

findExternalEditorPath( s : Switch, tag : String ) : String

The function findExternalEditorPath starts when "External Editor" is selected in properties of a script element in the Switch Designer. The function returns a value which is used as a path for the external editor.

function findExternalEditorPath( s : Switch, tag : String ) 
{
	var path = "";
	if ( tag == "Prop1" )
		path = "/mypath/myapp1";
	else if ( tag == "Prop2" )
		path = "/mypath/myapp2";
	else return path;
	
	if ( s.isMac() == false ) path = "C:" + path + ".exe";
	
	return path;
}