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 it 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 to the application (executable) used to edit a property set 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 folder portion of the path returned by the Environment.getApplicationPath( ) function
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

Property

Description

Application

The path to the application (executable) used to edit a property set

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 folder portion of the path returned by the Environment.getApplicationPath( ) function

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

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