@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-formsWizard-stepEditorWidget/research.md

@@ -0,0 +1,298 @@
+# Widget Research: cf.cplace.formsWizard.stepEditorWidget
+
+## Widget Identity
+
+- **Widget ID:** `cf.cplace.formsWizard.stepEditorWidget`
+- **Display Name (EN):** Step Editor
+- **Display Name (DE):** Schritt-Editor
+- **Repository:** cplace-forms-wizard
+- **Definition Class:** `cf.cplace.formsWizard.script.StepEditorWidgetDefinition`
+
+## Summary Description
+
+The Step Editor widget provides a dedicated editing interface for configuring individual wizard steps directly on Step pages, enabling detailed customization of step content, behavior, and type-specific settings.
+
+## Purpose & Core Functionality
+
+This widget serves as a **standalone step configuration tool** embedded on Step pages. It:
+
+1. **Automatically binds to the embedding Step**: Retrieves the step ID from the page it's embedded in
+2. **Renders step-type-specific editors**: Dynamically loads the appropriate editor component based on the step type (Form, Table, Decision, Info, Script)
+3. **Provides editing interface**: Displays editable controls for configuring step-specific settings
+4. **Enforces editing constraints**: Disables editing when the wizard is active or when the user lacks write permissions
+5. **Saves configuration changes**: Persists step configuration to the backend via REST API
+
+## Architecture & Components
+
+### Backend (Java)
+
+**Widget Definition:** `StepEditorWidgetDefinition.java` (cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/StepEditorWidgetDefinition.java:30)
+- Minimal configuration (only HEIGHT attribute from BASE_MIXIN)
+- Restricted to STEP type pages only: `checkIsOneOfTheseTypes(entity, embedding, FormsWizardAppTypes.STEP.TYPE)` (line 97)
+- Passes the embedding Step ID to the frontend via widget state (lines 75-78)
+
+**Configuration Type:** `CONFIGURATION.TYPE` (lines 100-105)
+- Single configuration attribute: `HEIGHT` (fixed height for the widget)
+
+**Embedding Context:**
+- Widget state includes `embeddedIn` property containing the Step page ID
+- This ID is automatically extracted from the page the widget is embedded on
+
+### Frontend (TypeScript/Angular)
+
+**Main Component:** `StepEditor.component.ts` (cf.cplace.formsWizard/assets/ts/stepEditor/StepEditor.component.ts:14)
+- Core component that orchestrates step editing
+- Receives `stepId` as input binding (line 128)
+- Fetches step type information from backend (line 44)
+- Dynamically compiles and loads the appropriate step-type-specific editor directive (lines 64-70)
+
+**Template Structure:** `stepEditor.html`
+```html
+<!-- Warning message when editing is disabled -->
+<div class="alert alert-warning" ng-hide="ctrl.isEditable()">
+  <p ng-repeat="message in ctrl.getDisableEditingMessages()">{{message}}</p>
+</div>
+
+<!-- Step editor container -->
+<div class="wizard-step-editor-container">
+  <div class="wizard-step-editor-header"></div>
+  <div class="wizard-step-editor-view">
+    <!-- Step-type-specific editor dynamically loaded here -->
+  </div>
+  <div class="wizard-step-editor-footer">
+    <button ng-disabled="!ctrl.isEditable()"
+            class="btn btn-primary pull-right"
+            ng-click="ctrl.save()">
+      {{ctrl.getMessage('save')}}
+    </button>
+  </div>
+</div>
+```
+
+**Key Functions:**
+- `getStepType(stepId)`: Retrieves step type and permissions from backend (line 20)
+- `createAndAppendEditorForStep(directive)`: Dynamically loads the appropriate editor (line 64)
+- `save()`: Delegates to the specific editor's save method (line 76)
+- `isEditable()`: Checks wizard activation state and permissions (line 91)
+- `getDisableEditingMessages()`: Returns array of reasons why editing is disabled (line 99)
+
+**Services:**
+- `StepEditorService`: Handles backend communication for step type and layout data
+- `StepTypeToDirectiveService`: Maps step types to their corresponding editor directives
+
+## Use Cases
+
+### Primary Use Case: Direct Step Configuration
+
+**When to use:** When working on a specific Step page and needing to configure its detailed settings.
+
+**Workflow:**
+1. User navigates to a Step page (type: `cf.cplace.formsWizard.step`)
+2. The Step Editor widget automatically appears on the page
+3. The widget loads the appropriate editor based on the step's type
+4. User configures step-specific settings (form fields, table columns, etc.)
+5. User clicks Save to persist changes
+6. Widget shows success/failure notification
+
+### Specific Scenarios
+
+1. **Designing form step fields**: Configure which attributes to display, layout (one/two column), field order, and validation rules
+2. **Setting up table step columns**: Define which columns to show in a table step and their configuration
+3. **Configuring decision step options**: Set up branching logic and decision options
+4. **Customizing info step content**: Design informational content display
+5. **Developing script step logic**: Write and test server-side scripts for custom behavior
+
+### Comparison with Related Widget
+
+**Step Editor Widget vs. Step Editor for Wizard Widget:**
+
+| Aspect | Step Editor Widget (this) | Step Editor for Wizard Widget |
+|--------|---------------------------|-------------------------------|
+| **Embedding Location** | On Step pages | On Wizard pages |
+| **Step Selection** | Automatic (the page itself) | Manual (via table row selection) |
+| **Context** | Focused, single-step editing | Quick editing in wizard context |
+| **Additional Attributes** | None (step attributes in sidebar) | Shows Title, Description, Next |
+| **Use Case** | Deep configuration of one step | Quick adjustments while designing wizard flow |
+
+## Configuration Options
+
+### Widget Configuration
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `height` | Number | No | Fixed height for the widget (inherited from BASE_MIXIN.HEIGHT) |
+
+The widget has minimal configuration as it derives most behavior from:
+- The step ID from the embedding page
+- The step's type (determines which editor to load)
+- The wizard's active state
+- User permissions
+
+### Editing Constraints
+
+The widget enforces these constraints (StepEditor.component.ts:91-110):
+
+1. **Read-only when wizard is active**:
+   - Prevents editing steps when the parent wizard is deployed/activated
+   - Displays message: "wizardIsActive"
+
+2. **Read-only without write permission**:
+   - Respects cplace permission model
+   - Displays message: "noWritePermission"
+
+3. **Editor-specific constraints**:
+   - Each step type editor may have additional constraints
+   - For example, FormStepEditor may restrict editing based on target type configuration
+
+## Relationship to Other Widgets
+
+### Default Page Layout Context
+
+The Step Editor widget appears on Step pages (`cf.cplace.formsWizard.step`) in a two-column layout:
+
+**Left Column (9/12 width):**
+- Step Editor Widget (height: 600px) - **This widget**
+
+**Right Column (3/12 width):**
+- Attributes Group Widget showing:
+  - Name
+  - Wizard (reference to parent wizard)
+  - Title (localized string)
+  - Description (rich text)
+  - Step Type (enumeration)
+  - Identifier (unique string)
+  - Target Types (multi-select enumeration)
+  - Navigation settings (Next, Skip To, Skip To Finish, etc.)
+
+**Below:**
+- Step Preview Widget (height: 500px) - Shows how the step will appear to end users
+
+This layout is defined in `FormsWizardAppTypes.STEP.WIDGET_CONTAINER_DEF` (FormsWizardAppTypes.java:171-384).
+
+### Related Widgets in the Forms Wizard Ecosystem
+
+| Widget | Purpose | Relationship |
+|--------|---------|--------------|
+| **Step Editor for Wizard Widget** (`cf.cplace.formsWizard.stepEditorForWizardWidget`) | Quick editing on Wizard pages | Uses the same `<cf-cplace-forms-wizard-step-editor>` component, but with different embedding context |
+| **Step Preview Widget** (`cf.cplace.formsWizard.stepPreview`) | Shows runtime view of step | Typically paired with Step Editor on Step pages |
+| **Wizard Step Manager Widget** (`cf.cplace.formsWizard.stepManager`) | Manages step list on Wizard pages | Works with Step Editor for Wizard Widget, not this widget |
+| **Wizard Analysis Widget** (`cf.cplace.formsWizard.wizardAnalysis`) | Validates wizard configuration | Shown on Wizard pages |
+| **Start Wizard Widget** (`cf.cplace.formsWizard.startWizardWidget`) | Launches wizards for end users | Consumes the configuration created with Step Editor |
+
+## Step Types Supported
+
+The widget supports editing for all registered step types. The system includes these built-in types:
+
+| Step Type | Description | Editor Component | Configuration |
+|-----------|-------------|------------------|---------------|
+| **Form Step** | Collects data via form fields | `FormStepEditor.component.ts` | Attribute selection, layout (one/two column), field ordering |
+| **Table Step** | Displays/edits tabular data | `TableStepEditor.component.ts` | Column configuration, table settings |
+| **Decision Step** | Branching logic based on user choices | `DecisionStepEditor.component.ts` | Decision options and routing |
+| **Info Step** | Displays informational content | `InfoStepEditor.component.ts` | Content display settings |
+| **Script Step** | Executes server-side scripts | `ScriptStepEditor.component.ts` | Script code and execution settings |
+
+**Extensibility:** Custom step types can be registered via the `StepTypeExtension` extension point. Each custom type must:
+1. Provide a step type identifier (via `StepTypeEnumProvider`)
+2. Register an editor directive (via `StepTypeToDirectiveService`)
+3. Implement the `WizardStepEditor<T>` interface
+
+## Technical Notes
+
+### Widget State
+
+The widget state is minimal (cfCplaceFormsWizardStepEditorWidgetDirective.ts:3-5):
+```typescript
+export interface WidgetState {
+  stepId: string;  // Not used by directive, but kept for compatibility
+}
+```
+
+The actual step ID is passed to the `<cf-cplace-forms-wizard-step-editor>` component via the `embeddedIn` property from the widget's configuration substitution (StepEditorWidgetDefinition.java:75-78).
+
+### Dynamic Editor Loading
+
+The widget uses AngularJS's `$compile` service to dynamically load step-type-specific editors:
+
+1. Fetch step type from backend (StepEditor.component.ts:44)
+2. Map step type to directive name (via `StepTypeToDirectiveService`)
+3. Create Angular element with directive
+4. Compile and append to DOM (lines 64-70)
+
+This allows the Forms Wizard plugin to be extended with new step types without modifying the core Step Editor widget.
+
+### Event Communication
+
+The widget relies on AngularJS event broadcasting:
+- **Listens for:** `ACTIVATION_STATE_CHANGED` - Refreshes UI when wizard is activated/deactivated (referenced by child editors)
+- **Broadcasts:** None directly, but child editors may broadcast step-specific events
+
+### Embedding Restrictions
+
+- Can ONLY be embedded as a widget (not in search, dialogs, etc.)
+- Can ONLY be placed on pages of type `cf.cplace.formsWizard.step`
+- Automatically bound to the embedding Step page (checkEmbeddableIn enforcement at StepEditorWidgetDefinition.java:95-98)
+
+### REST API
+
+**Step Type Endpoint:**
+- URL: `{context}/cplace-fe/cf.cplace.formsWizard/steps/steptype?stepId={stepId}`
+- Returns: `StepType` object with `stepType`, `writePermitted`, and `active` properties
+
+**Step Layout Endpoints:**
+- GET: `{context}/cplace-fe/cf.cplace.formsWizard/steps/{stepId}/layout`
+- POST: `{context}/cplace-fe/cf.cplace.formsWizard/steps/{stepId}/layout`
+- Used by `StepLayoutService` to retrieve and save step-specific configuration
+
+## Key Differences from Step Editor for Wizard Widget
+
+While both widgets share the same core `<cf-cplace-forms-wizard-step-editor>` component, they differ significantly in context and usage:
+
+### Step Editor Widget (this widget)
+
+**Purpose:** Deep, focused editing of a single step
+**Location:** Embedded on Step pages
+**Step Selection:** Automatic (the embedding page itself)
+**Layout:** Paired with Attributes Widget (for step metadata) and Step Preview Widget
+**Attributes Display:** Step attributes shown separately in Attributes Widget sidebar
+**Use Case:** When you want to focus on configuring one specific step in detail
+
+### Step Editor for Wizard Widget
+
+**Purpose:** Quick editing while maintaining wizard overview
+**Location:** Embedded on Wizard pages
+**Step Selection:** Manual (user selects from Wizard Step Manager table)
+**Layout:** Shares space with Wizard Step Manager and Wizard Analysis widgets
+**Attributes Display:** Basic attributes (Title, Description, Next) shown inline above editor
+**Use Case:** When you want to adjust multiple steps while seeing the overall wizard structure
+
+## Key Source Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| **StepEditorWidgetDefinition.java** | cf.cplace.formsWizard/src/main/java/cf/cplace/formsWizard/script/ | Widget definition, embedding restrictions |
+| **stepEditorWidgetDefinition.htm** | cf.cplace.formsWizard/src/main/resources/cf/cplace/formsWizard/script/ | Widget template |
+| **cfCplaceFormsWizardStepEditorWidgetDirective.ts** | cf.cplace.formsWizard/assets/ts/directives/ | Widget directive (minimal, mostly passes through) |
+| **StepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/stepEditor/ | Core editor component, dynamic loading logic |
+| **stepEditor.html** | cf.cplace.formsWizard/assets/ts/stepEditor/ | Editor template |
+| **StepEditorService.ts** | cf.cplace.formsWizard/assets/ts/stepEditor/_services/ | Backend communication service |
+| **StepLayoutService.ts** | cf.cplace.formsWizard/assets/ts/stepEditor/_services/ | Step layout data service |
+| **WizardStepEditor.ts** | cf.cplace.formsWizard/assets/ts/stepEditor/ | Base class for step-type-specific editors |
+| **FormStepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/step/form/editor/ | Form step editor implementation |
+| **TableStepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/step/table/editor/ | Table step editor implementation |
+| **DecisionStepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/step/decision/editor/ | Decision step editor implementation |
+| **InfoStepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/step/info/editor/ | Info step editor implementation |
+| **ScriptStepEditor.component.ts** | cf.cplace.formsWizard/assets/ts/step/script/editor/ | Script step editor implementation |
+| **messages_en.properties** | cf.cplace.formsWizard/src/main/resources/cf/cplace/formsWizard/ | English localization |
+| **messages_de.properties** | cf.cplace.formsWizard/src/main/resources/cf/cplace/formsWizard/ | German localization |
+
+## Summary
+
+The Step Editor widget is a specialized configuration interface that:
+- Provides deep, focused editing of individual wizard steps
+- Automatically binds to the Step page it's embedded on
+- Dynamically loads the appropriate editor based on step type
+- Enforces wizard activation and permission constraints
+- Works in tandem with the Attributes Widget (for step metadata) and Step Preview Widget (for visual preview)
+- Shares core editing components with the Step Editor for Wizard Widget but operates in a different context (Step pages vs. Wizard pages)
+
+This widget is essential for detailed step configuration in the Forms Wizard system, offering a focused editing experience for developers and administrators building complex wizard workflows.