@cplace/mcp-server 1.5.3 → 1.6.1

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

@@ -1,298 +0,0 @@
-# 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.