@enfocussw/switch-scripting-context 0.1.0

package/docs/switch-project/property-editors.md

@@ -0,0 +1,249 @@
+---
+id: property-editors
+category: switch-project
+order: 15
+summary: "Property editor types, string return values, literal editors, dropdowns"
+triggers:
+  - "Defining property editors in XML or reading property values in code"
+---
+
+# Property Editors
+
+Property editors determine how a user enters a value in Switch Designer, and what string is
+returned by `getPropertyStringValue()` at runtime. They're set in the XML declaration via the
+`Editor` and `Type` attributes on a custom property — see
+[script-declaration.md](script-declaration.md) for the surrounding attribute grammar.
+
+All property values are returned as `string` or `string[]`. `getPropertyType()` returns one of a
+fixed set of `PropertyType` values (`literal`, `string`, `number`, `date`, `boolean`, `filepath`,
+`folderpath`, `regex`, `oauthtoken`, etc. — see [enums.md](../switch-api/enums.md)) describing what kind of
+value is actually present; `literal` is only one of these, not a binary "literal vs. user-entered"
+flag. Use it before interpreting the returned string, e.g. to check for a literal editor's constant
+before comparing it.
+
+`Editor` is a `;`-joined list: the inline editor's token (if any) first, then modal editor tokens in
+the order they're offered. `Type` follows from which editor(s) are chosen — see the tables below and
+[the Type reference](script-declaration.md#type-reference).
+
+---
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Inline editors
+- Modal editors
+- Literal editors
+- Extra XML attributes for certain editors
+- Common practices
+  - A property whose shape varies by a type selector
+- Notes
+<!-- docs-index:contents end -->
+
+## Inline editors
+
+The inline editor slot is always the single token `inline` in `Editor` — what differs is `Type`.
+
+| Editor / Type | Resulting `getPropertyStringValue()` value |
+|---|---|
+| `Editor="inline" Type="string"` | Single-line text as entered |
+| `Editor="inline" Type="password"` | Text as entered (displayed masked) |
+| `Editor="inline" Type="number"` | Integer as a string |
+| `Editor="inline" Type="time"` | `"hh:mm"` (zero-padded, e.g. `"09:05"`) |
+| `Editor="inline" Type="date"` | Date as entered |
+| `Editor="inline" Type="datetime"` | Date and time as entered |
+| `Editor="inline" Type="bool"` | `"No"` or `"Yes"` |
+| `Editor="inline" Type="enum:Item1;Item2;..."` | The selected item string (one of the declared values) |
+
+> The `rational` (decimal) inline editor is not allowed in Node.js scripts. Don't declare
+> `Type="rational"`.
+
+---
+
+## Modal editors
+
+Additional editor tokens appended after `inline` (or used alone, with no inline component). These
+open a dialog when the user clicks the editor button. All have `Type="string"` unless noted.
+
+| `Editor` token | Resulting `getPropertyStringValue()` value |
+|---|---|
+| `choosefile` | Absolute file path as a string |
+| `choosefolder` | Absolute folder path as a string |
+| `regexp` | Regular expression string as entered |
+| `filetype` | Filename pattern(s) for the selected file type |
+| `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
+| `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks) |
+| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one. Unconfirmed, so treat the name as unverified. |
+| `description` | Multi-line text as a single string (may include newlines) |
+| `scriptexp` | Result of script expression evaluated in job context, as a string |
+| `sltextwithvar` | Single-line text with variables substituted, as a string |
+| `mltextwithvar` | Multi-line text with variables substituted, as a string |
+| `conditionwithvar` | `"true"` or `"false"` after evaluating condition with variables |
+| `filepatterns` | `string[]` — one pattern string per entry |
+| `folderpatterns` | `string[]` — one pattern string per entry |
+| `stringlist` (`Type="stringlist"`) | `string[]` — one string per line |
+| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](script-declaration.md#extraproperties) |
+| `external`, `external2`, … | File path to a property set edited by an external companion app |
+
+> Duplicate tokens in `Editor` are meaningless — each modal editor can only be offered once, except
+> `external` which can appear multiple times with numeric suffixes (`external`, `external2`, `external3`, …).
+
+---
+
+## Literal editors
+
+A literal editor makes a property return a **fixed string** regardless of user input. Combine it
+with another editor in the `Editor` chain (e.g. `Editor="default;choosefolder"`) to offer the
+constant as one of the choices; all literal tokens have `Type="string"`.
+
+Always call `getPropertyType()` first to check whether the value is a literal before comparing the
+string.
+
+Use the matching literal editor for a keyword-style value like "Default", "None", or "Automatic"
+instead of making it a typed string default — e.g. `default` instead of a `Default`
+attribute set to the literal text `"Default"`. Typing the keyword as an ordinary string default lets
+a user accidentally change it to arbitrary text and loses the `PropertyType.Literal` signal the
+script relies on. `none` is specifically the sanctioned way to let a property hold an empty value
+under `Validation="Standard"` — combine it into the `Editor` chain instead of relaxing to
+`Validation="None"` just to permit emptiness.
+
+| `Editor` token | `getPropertyStringValue()` returns |
+|---|---|
+| `default` | `"Default"` |
+| `none` | `""` (empty string) |
+| `automatic` | `"Automatic"` |
+| `nofiles` | `"No Files"` |
+| `allfiles` | `"All Files"` |
+| `allotherfiles` | `"All Other Files"` |
+| `nofolders` | `"No Folders"` |
+| `allfolders` | `"All Folders"` |
+| `allotherfolders` | `"All Other Folders"` |
+| `next` | `"Next"` |
+| `current` | `"Current"` |
+
+`nofiles`/`allfiles`/`allotherfiles` and `nofolders`/`allfolders`/`allotherfolders` are not
+general-purpose — every real use of them is a connection **include/exclude filter mask** (an
+`IncludeMask`/`ExcludeMask`, or `IncludeFolderMask`/`ExcludeFolderMask`, on a `ConnectionType="Filter"`
+connection). Switch Designer labels them "No/All/All other jobs" and "No/All folders" in that
+context, not the XML token names above. See [Common practices](#common-practices) below for the
+exact chain.
+
+`next` and `current` exist in the editor grammar but have no confirmed script-facing use case — no
+built-in Switch flow element declares a property using them, and Enfocus's own property-editor
+documentation omits both (along with `allotherfolders`, apparently by oversight, since it's used the
+same way as `allotherfiles`). Don't reach for `next`/`current` without confirming a concrete need
+first.
+
+---
+
+## Extra XML attributes for certain editors
+
+**Dropdown (`Type="enum:..."`)** — items are embedded in the `Type` value itself:
+`Type="enum:Option A;Option B;Option C"`.
+
+**`askplugin` / `askplugin2`** — add a `SelectFromLibMes` (single) or `SelectManyFromLibMes` (multi)
+attribute to the property element to set a custom dialog message.
+
+**`stringlist`** — add a `StringListMes` attribute to show a custom message in the editor dialog.
+
+**`choosefile`** — add `Opaque="true"` to include the referenced file as an opaque payload when a
+flow is exported.
+
+**`external`** (and `external2`, …) — add matching-suffixed `ExternalEditorName`,
+`ExternalValueOverlay`, `ExternalApplication`, `ExternalArgForNew`, `ExternalArgForEdit`, and
+`ExternalFileFormat` (`Custom` or `Switch`) attributes.
+
+---
+
+## Common practices
+
+The following are recommended conventions for pairing property kinds with editor chains, not
+restrictions enforced by Switch — a script writer can combine editors differently if asked to.
+
+Enable the dynamic editors (`sltextwithvar`/`mltextwithvar` and `conditionwithvar`, `scriptexp`)
+wherever the value could plausibly vary per job — the rows below already reflect this. Conversely,
+don't add them to a property whose value is inherently static (e.g. a dataset name, or anything a
+`Dependency` master needs to read at flow-configuration time) — offering a variable/script option
+there just invites a value the script can't sensibly use.
+
+**App guideline (mandatory for apps, recommended for scripts):** make sure at least one editor in
+the chain works without an add-on Switch module: `scriptexp` requires the Scripting Module, so never
+offer it as the property's only editor — pair it with a module-free option (e.g. `inline` or
+`sltextwithvar`) so the property still works for a user without that module.
+
+| Property kind | Recommended `Editor` chain | Why |
+|---|---|---|
+| Secret (password, token, API key) | `inline` only, with `Type="password"` and **`Subtype=""`** (not `"inline"`) | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. `password` is a `Type`, not an editor token — there is no `password` entry in the [modal editor](#modal-editors) list, so `Editor="password"` is wrong. `Subtype="inline"` (the usual value for a single inline editor, per [script-declaration.md](script-declaration.md#custom-property-elements-elementfields)) is rejected at script load with "editor that is not supported in Node.js scripting"; Switch Designer itself saves `Type="password"` with `Subtype=""`. |
+| Scalar job-specific value (job ID, copy count, company name, date, etc.) | `inline` (`Type` matching the value) + `sltextwithvar` + `scriptexp` | Hard-coded default, plus dynamic substitution and full expression evaluation. |
+| Array/list job-specific value | `stringlist` + `mltextwithvar` + `scriptexp` | One item per line. **Caveat:** the intent is that every path returns a `string[]`, but the [modal editor table](#modal-editors) lists `mltextwithvar` as returning a single string, and which one holds for this chain is unverified. Handle both — split on newlines when a bare string comes back. |
+| Structured blob text (XML/JSON/HTML, email body) | `description` + `mltextwithvar` + `scriptexp` | Free multi-line text suits a single blob of content better than a line-per-item list. |
+| Boolean used as a `Dependency` master | `inline` only | Other properties' visibility depends on a value known at design time. |
+| Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
+| Enum (`Type="enum:..."`) | `inline` only, always | No editor guarantees a var/expression result matches one of the declared items. |
+| File/folder path that must exist for the app to work | `choosefile`/`choosefolder` only | Switch validates the picked path exists at flow start. |
+| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [flow-element.md](../switch-api/flow-element.md#properties) if the path is needed later in the flow. |
+| Connection include-mask filter (which jobs pass through) | `allfiles;allotherfiles;types;filepatterns;regexp;scriptexp`, `Default="All Files"`, `Subtype="allfiles"` | Matches Switch's own built-in connection filter properties exactly — `Default`/`Subtype` must hold the chosen literal's exact rendered string. Folder version: `allfolders;allotherfolders;folderpatterns;regexp;scriptexp` with `Default="All Folders"`, `Subtype="allfolders"`. |
+| Connection exclude-mask filter (which jobs are blocked) | `nofiles;types;filepatterns;regexp;scriptexp`, `Default="No Files"`, `Subtype="nofiles"` | Same reasoning as the include mask, starting from `nofiles` instead since there's no "exclude all/all other" case. Folder version: `nofolders;folderpatterns;regexp;scriptexp` with `Default="No Folders"`, `Subtype="nofolders"`. |
+
+`regexp`, `filetype`/`types`, `askplugin`/`askplugin2`, `oauth`, and `external` can technically be
+combined with `sltextwithvar`/`scriptexp` too, but this is uncommon in practice and not covered by a
+dedicated row above.
+
+### A property whose shape varies by a type selector
+
+When what a property must hold depends on another property's value — a map for one type, an
+ordered list for another, a pair of labelled strings for a third — don't reach for one property
+holding JSON or a hand-rolled line format. Declare an enum master and one dependent per shape, each
+with the editor that natively fits it, and read only the dependent the master currently shows.
+
+The shapes then need no parsing at all in the common cases, and the property pane shows one
+type-appropriate editor with a label that explains itself instead of a text box whose format lives
+in the documentation:
+
+```xml
+<!-- master: enum, inline only, so the value is known at flow-configuration time -->
+<QType UserDefined="true" Type="enum:(not used);List;Ordered;Pair" Editor="inline" Subtype="inline"
+       LocalizedTagName="Type" Tooltip="" DetailedInfo="" Validation="Standard"
+       Default="(not used)">(not used)</QType>
+
+<!-- one dependent per shape; each is hidden unless its condition holds -->
+<QList UserDefined="true" Type="stringlist" Editor="stringlist" Subtype="stringlist"
+       Dependency="QType" DependencyCondition="Equals" Dependencyvalue="List"
+       LocalizedTagName="Items" Tooltip="" DetailedInfo="" Validation="Standard"></QList>
+<QLow  UserDefined="true" Type="string" Editor="description" Subtype=""
+       Dependency="QType" DependencyCondition="Equals" Dependencyvalue="Pair"
+       LocalizedTagName="What a low value means" Tooltip="" DetailedInfo=""
+       Validation="Standard" Default=""></QLow>
+```
+
+Adding `(not used)` to the master's items makes it double as the group's on/off switch, so the
+group needs no separate boolean.
+
+Two constraints come with the pattern:
+
+- The master must be an enum or a boolean with `inline` only, per the rows above. A dynamic master
+  makes the visible set differ per job, which the dependents' own editors cannot account for.
+- Reading a hidden dependent throws `"Invalid tag: <tag>"`. Check the master's value, or call
+  `hasProperty(tag)`, before every read — see
+  [script-declaration.md § Dependency](script-declaration.md#custom-property-elements-elementfields).
+  This bites hardest in a loop over jobs or connections, where the throw repeats on every
+  invocation.
+
+A shape the master cannot enumerate, or one that must vary per job, is the case this pattern does
+not cover; that is where a single `description` property holding a structured blob is the honest
+answer.
+
+---
+
+## Notes
+
+- **OAuth 2.0**: endpoint, client ID/secret, scope, and redirect ports are configured per-property
+  in a matching `<ExtraProperties>` child element (see
+  [script-declaration.md § ExtraProperties](script-declaration.md#extraproperties)), not in
+  `Editor`/`Type`. The script receives a ready-to-use access token string via
+  `getPropertyStringValue()`.
+- **External editor**: requires a separate companion application. The script receives a file path to
+  the property set file. Entry point `findExternalEditorPath` resolves the editor executable path.
+  One of these two must be true — either a dependent property named `Application` (see
+  [Dependency](script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
+  the script implements `findExternalEditorPath` — see
+  [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks).