# UI Binding — Pairing a Process with a UserInterface File

A process and its UI live in the same folder. The UI reads and writes ProcessContext variables;
the user's button presses fire named events that the process handles.

---

## Folder Layout

```
src/<Module>/
└── PR/
    └── <FlowName>/
        ├── <FlowName>Process.processflow.xml   ← defines ProcessContext + actions
        └── <FlowName>UI.userinterface.xml       ← optional; references ProcessContext vars
```

Both files share the `PR/<FlowName>/` directory. Neither is inside a subfolder.

**Real example (paired):**

```
src/Visit/PR/Visit_Reschedule/
  Visit_RescheduleProcess.processflow.xml
  Visit_RescheduleUI.userinterface.xml
```

**Real example (no UI — pure logic flow):**

```
src/Visit/PR/Visit_ChangeStatusWizard/
  Visit_ChangeStatusWizardProcess.processflow.xml
```

No UI file: the flow is driven entirely by LOAD, DECISION, CONFIRM, and LOGIC actions.

---

## VIEW Action — How the Process References the UI

```xml
<Action name="ShowDetail" actionType="VIEW">
  <UIDescription>Visit::RescheduleUI</UIDescription>
  <Events>
    <Event name="rescheduleVisit" action="WizardValidation" />
  </Events>
</Action>
```

-   `<UIDescription>` — the UI's fully-qualified name: `<Module>::<FlowName>UI`.
    This is the `name` attribute on the root `<UIDescription>` element in the companion file.
-   `<Events>` — maps UI-fired event names to process action names.
    Every `<Event name="X" action="Y">` must have `action="Y"` pointing to an existing action.

**Real file:** `src/Visit/PR/Visit_Reschedule/Visit_RescheduleProcess.processflow.xml` (line 99-104).

---

## UI Side — Binding to ProcessContext

Inside the `.userinterface.xml`, fields bind to `ProcessContext::<VarName>.<property>`:

```xml
<InputArea name="DateFrom">
  <Bindings>
    <Resource target="Label" type="Label"
              id="dateFromLabel" defaultLabel="Start Date" />
    <Binding target="Value"
             binding="ProcessContext::RescheduleVisitBo.dateFrom"
             bindingMode="TWO_WAY" />
  </Bindings>
</InputArea>
```

-   `ProcessContext::RescheduleVisitBo` must be declared in the process's `<Declarations>`.
-   `.dateFrom` must be a property on `BoWizardRescheduleVisit`.
-   `bindingMode="TWO_WAY"` — field writes back to the BO; use `ONE_WAY` for read-only display.

**Real file:** `src/Visit/PR/Visit_Reschedule/Visit_RescheduleUI.userinterface.xml`.

---

## UI Side — Firing Events to the Process

A button in the UI fires a named event. The process's VIEW action maps that event to an action:

**UI:**

```xml
<MenuItem directlyVisible="true" itemId="rescheduleVisit">
  <Events>
    <ButtonPressedEvent event="rescheduleVisit" />
  </Events>
</MenuItem>
```

**Process (matching VIEW action):**

```xml
<Events>
  <Event name="rescheduleVisit" action="WizardValidation" />
</Events>
```

The string `"rescheduleVisit"` must be identical in both files. A mismatch causes the button to
do nothing (silent failure — no build error, no runtime exception).

---

## Passing Data from UI Events

For list selection and context menus, the event carries item properties defined via `<Params>`:

**UI (ItemSelectedEvent):**

```xml
<ItemSelectedEvent event="itemSelected">
  <Params>
    <Param name="pKey"   value=".pKey" />
    <Param name="status" value=".status" />
  </Params>
</ItemSelectedEvent>
```

**Process (receiving action):**

```xml
<Action name="LoadSelectedItem" actionType="LOAD" type="BoOrder">
  <Parameters>
    <Input name="pKey" value="Event.pKey" />
  </Parameters>
  <Return name="ProcessContext::SelectedOrder" />
  <TransitionTo action="ShowDetail" />
</Action>
```

`Event.pKey` is only available in the action that handles the `itemSelected` event.

---

## When NOT to Pair a UI

A process does not need a UI file when it:

-   Only loads data and calls BL methods (status change flows, background validation).
-   Invokes a sub-process that owns the UI.
-   Shows only CONFIRM dialogs (which are framework-rendered, not custom UI).

**Real example (no UI):**
`src/Visit/PR/Visit_ChangeStatusWizard/Visit_ChangeStatusWizardProcess.processflow.xml` —
loads a BO, runs a LOGIC check, branches to CONFIRM dialogs, calls LOGIC methods, ends. Zero VIEW
actions, zero companion UI file.

---

## Naming Conventions

| Element      | Convention                          | Example                                   |
| ------------ | ----------------------------------- | ----------------------------------------- |
| Process name | `<Module>::<FlowName>Process`       | `Visit::RescheduleProcess`                |
| UI name      | `<Module>::<FlowName>UI`            | `Visit::RescheduleUI`                     |
| Process file | `<FlowName>Process.processflow.xml` | `Visit_RescheduleProcess.processflow.xml` |
| UI file      | `<FlowName>UI.userinterface.xml`    | `Visit_RescheduleUI.userinterface.xml`    |
| Folder       | `src/<Module>/PR/<FlowName>/`       | `src/Visit/PR/Visit_Reschedule/`          |

Note the underscore in folder and file names vs the `::` separator in XML `name` attributes.

---

## Checklist: Process ↔ UI Pairing

-   [ ] UI `<UIDescription name="...">` matches the process's `<UIDescription>` child text exactly
-   [ ] Every `<Event name="X">` in the VIEW action has a matching `<ButtonPressedEvent event="X">` in the UI
-   [ ] Every UI `<Binding binding="ProcessContext::<VarName>.*">` has `<VarName>` declared in the process
-   [ ] All UI-bound variables are populated (LOAD/CREATE/LOGIC) before the VIEW action fires
-   [ ] Both files are in the same `PR/<FlowName>/` folder — no nested subfolders