@cplace/test-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,211 @@
+# Start Wizard Widget Research
+
+## Widget Identification
+
+- **Widget ID**: `cf.cplace.formsWizard.startWizardWidget`
+- **Repository**: `cplace-forms-wizard`
+- **Definition Class**: `cf.cplace.formsWizard.script.StartWizardWidgetDefinition`
+- **App**: Forms Wizard Launcher (`FormsWizardExecutionApp`)
+
+## Purpose
+
+The Start Wizard Widget provides a button that launches a Forms Wizard, which is a multi-step guided form interface for creating or managing pages in cplace. The widget acts as an entry point to initiate wizard-based workflows from within pages, type definitions, or rich strings.
+
+## Core Functionality
+
+The widget creates an interactive button that:
+1. Launches a configured Forms Wizard when clicked
+2. Passes context information (embedding entity, workspace, data sources) to the wizard
+3. Optionally refreshes the embedding page or connected tables after wizard completion
+4. Can be dynamically controlled (visibility, enabled state, tooltip) via Low-Code scripts
+
+## Use Cases
+
+### 1. Guided Page Creation
+Replace standard page creation with a multi-step wizard that guides users through data entry with validation and conditional logic.
+
+**Scenario**: Creating project proposals with multiple related information sections, dependencies, and validation rules.
+
+### 2. Data Collection from Connected Tables
+Launch a wizard to process selected rows from a connected table, enabling batch operations or data enrichment workflows.
+
+**Scenario**: Selecting multiple tasks from a table and launching a wizard to bulk-assign resources or update statuses.
+
+### 3. Contextual Form Entry
+Embed the widget within specific page types to provide contextual actions that create related entities with pre-filled information from the parent page.
+
+**Scenario**: From a project page, launch a wizard to create a new milestone that automatically inherits project context and workspace.
+
+### 4. External User Data Collection
+Enable external users (not logged into cplace) to submit structured data through a wizard interface with optional CAPTCHA protection.
+
+**Scenario**: Collecting customer feedback, service requests, or applications from external users via public forms.
+
+### 5. Multi-Step Business Processes
+Implement complex business workflows that span multiple forms, validation steps, and conditional branching based on user input.
+
+**Scenario**: Employee onboarding process with steps for personal data, equipment requests, access provisioning, and final confirmation.
+
+### 6. Dynamic Form Availability
+Use scripts to conditionally show/hide or enable/disable the wizard button based on user permissions, page state, or business rules.
+
+**Scenario**: Only show "Create Invoice" wizard when a project has completed milestones and user has finance permissions.
+
+## Configuration Concepts
+
+### Main Configuration Options
+
+#### 1. **Wizard Reference** (Required)
+- Links to a specific Forms Wizard (Page of type `cf.cplace.formsWizard.wizard`)
+- The wizard defines the steps, forms, logic, and target types
+
+#### 2. **Button Appearance**
+- **Title**: Optional widget frame title
+- **Button Label**: Customizable button text (defaults to widget name)
+- **Show Frame**: Toggle to show/hide the widget frame container
+
+#### 3. **Data Source Configuration**
+Three mutually exclusive options for providing data to the wizard:
+
+- **Search**: Execute a saved search to provide pages to the wizard
+  - Includes sort column and sort order options
+
+- **Connected Table**: Reference a table widget on the same page
+  - **Table Result Mode**: Controls whether wizard processes selected rows or all search results
+  - Enables workflows where users select data before launching wizard
+
+- **Explicit Selection**: Manually specify pages to pass to the wizard
+  - Direct page references configured in the widget
+
+#### 4. **Embedding Context**
+- Specifies the workspace context for the wizard execution
+- Defaults to the embedding entity's workspace
+- Can be explicitly set for cross-workspace scenarios
+
+#### 5. **Refresh Behavior**
+- **Refresh Embedding Page After Finish**: Reloads the page containing the widget after wizard completion
+- **Refresh Connected Table**: Specifies a connected table widget to reload after completion, automatically loading the most recent element
+
+#### 6. **Low-Code Script Configuration**
+Optional script that returns an object controlling button behavior:
+
+```javascript
+return {
+  visible: true,    // Controls button visibility
+  enabled: true,    // Controls whether button is clickable
+  tooltip: "..."    // Optional tooltip text (can be localized string)
+};
+```
+
+**Script Context**:
+- `embeddingPage`: The page containing the widget (if embedded in a page)
+- Access to `Search` and `Filters` classes for dynamic logic
+
+**Use Cases**:
+- Conditional visibility based on page state or attributes
+- Disable button with explanatory tooltip when prerequisites aren't met
+- Dynamic tooltips providing context about what the wizard will do
+
+### Embedding Capabilities
+
+The widget can be embedded in:
+- Pages (standard page content)
+- Type Definitions (available on all pages of that type)
+- Rich String attributes (within rich text content)
+- Attributes Group widgets (as a nested widget)
+- Connected Attributes Group widgets (as a nested widget)
+
+## Related Components
+
+### Forms Wizard Ecosystem
+
+1. **Wizard (Page Type)**: `cf.cplace.formsWizard.wizard`
+   - Defines the complete wizard structure
+   - Configures start step, final steps, and available steps
+   - Settings for progress bar, auto-persist, external access
+   - Optional cleanup scripts and summary pages
+
+2. **Step (Page Type)**: `cf.cplace.formsWizard.step`
+   - Individual steps in the wizard flow
+   - Types include: Form, Script, Info, Summary, Table
+   - Configures next possible steps, skip logic, and target types
+
+3. **Forms Wizard App**: Main configuration app
+   - Manages wizard and step definitions
+   - Provides editor widgets for step configuration
+
+4. **Forms Wizard Launcher App**: Execution app
+   - Provides the Start Wizard Widget
+   - Can replace standard page creation with wizard flows
+   - Supports external access for non-logged-in users
+
+### Integration Points
+
+1. **Connected Table Widgets**: The widget can trigger based on table selections and refresh tables after completion
+
+2. **Search Integration**: Leverages saved searches to provide data to wizards
+
+3. **Type System**: Can intercept page creation for configured trigger types, replacing standard forms with wizards
+
+4. **Workspace Context**: Respects workspace boundaries and permissions
+
+5. **Localization**: Full internationalization support for buttons, tooltips, and wizard content
+
+## Technical Architecture
+
+### Backend Components
+
+- **StartWizardWidgetDefinition**: Widget definition class extending `WidgetDefinition`
+- **StartWizardHandler**: Handles wizard launch requests
+- **StartWizardScriptExecutionProcessor**: Executes Low-Code scripts for button configuration
+- **StartWizardParameters**: Encapsulates wizard launch context and parameters
+- **WizardPermissionsHelper**: Validates wizard activation state and user permissions
+
+### Frontend Components
+
+- **cfCplaceFormsWizardStartWizardWidgetDirective**: AngularJS directive rendering the button
+- **StartWizardCtrl**: Controller managing widget state and button behavior
+
+### State Management
+
+The widget maintains state including:
+- Button label, visibility, enabled state, tooltip
+- Wizard reference and embedding context
+- Data source configuration (search, connected table, or selection)
+- Refresh behavior settings
+- Component identifiers for post-completion updates
+
+## Key Attributes from Type Definition
+
+From `FormsWizardWidgetTypes.START_WIZARD_WIDGET`:
+
+| Attribute | Type | Purpose |
+|-----------|------|---------|
+| `TITLE` | LocalizedString | Widget frame title |
+| `BUTTON_LABEL` | LocalizedString | Button display text |
+| `WIZARD` | PageReference | Reference to wizard to launch |
+| `DATA_SOURCE` | AttributeGrouping | Configures how data is provided (search/table/selection) |
+| `SEARCH` | String | Saved search reference |
+| `SORT_COLUMN` | String | Search result sorting |
+| `SORT_ORDER` | String | Sort direction |
+| `CONNECTED_TABLE` | String | Table widget reference |
+| `TABLE_RESULT_MODE` | Enum | Selection vs all results |
+| `SELECTION` | PageReference (Multi) | Explicit page selection |
+| `SHOW_FRAME` | Boolean | Show/hide widget frame |
+| `SCRIPT` | Script | Low-Code button configuration |
+| `EMBEDDING_CONTEXT` | String | Workspace context |
+| `REFRESH_CONNECTED_TABLE` | String | Table to refresh on completion |
+
+## Permissions and Security
+
+- Wizard must be marked as "Active" to be launchable (`WizardPermissionsHelper.isWizardActive`)
+- User permissions are checked for:
+  - Read access to configured target workspaces
+  - Write access to configured trigger types
+  - Standard page creation permissions for target types
+- External access mode uses a configured external access user
+- Optional CAPTCHA for external wizard access
+
+## Summary
+
+The Start Wizard Widget is a versatile entry point for launching multi-step Forms Wizards within cplace. It bridges the gap between page context and guided data entry workflows, supporting use cases from simple page creation to complex business processes. The widget's configuration flexibility enables both simple button functionality and sophisticated data-driven workflows with conditional logic, table integration, and contextual awareness.

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

@@ -0,0 +1,183 @@
+# Widget Research: cf.cplace.formsWizard.stepEditorForWizardWidget
+
+## Widget Identity
+
+- **Widget ID:** `cf.cplace.formsWizard.stepEditorForWizardWidget`
+- **Display Name (EN):** Step Editor for Forms Wizards
+- **Display Name (DE):** Schritt-Editor für Wizards
+- **Repository:** cplace-forms-wizard
+- **Definition Class:** `cf.cplace.formsWizard.script.StepEditorForWizardWidgetDefinition`
+
+## Summary Description
+
+The Step Editor for Forms Wizards widget provides inline editing capabilities for wizard steps directly from the Wizard page, enabling quick configuration of step content without navigating away from the wizard context.
+
+## Purpose & Core Functionality
+
+This widget serves as a **contextual step configuration tool** embedded in Wizard pages. It:
+
+1. **Responds to step selection**: Listens for row selection events from the Wizard Step Manager table widget
+2. **Displays step attributes**: Shows editable fields for Title, Description, and Next Step references
+3. **Renders step-type-specific editors**: Dynamically loads the appropriate editor component based on the step type (Form, Table, Decision, Info, Script)
+4. **Enforces editing constraints**: Disables editing when the wizard is active or when the user lacks write permissions
+
+## Architecture & Components
+
+### Backend (Java)
+
+**Widget Definition:** `StepEditorForWizardWidgetDefinition.java`
+- Minimal configuration (only HEIGHT attribute)
+- Restricted to WIZARD type pages only (`checkIsOneOfTheseTypes(entity, embedding, FormsWizardAppTypes.WIZARD.TYPE)`)
+
+**REST Controller:** `WizardStepEditorController.java`
+- Endpoint: `/cf.cplace.formsWizard/wizard/stepeditor`
+- Returns rendered HTML for step attributes (Title, Description, Next)
+
+**Service:** `WizardStepEditorService.java`
+- Retrieves and renders step attributes as editable HTML widgets
+
+### Frontend (TypeScript/Angular)
+
+**Main Component:** `StepEditorForWizard.component.ts`
+- Listens to `StaticTableCtrl.EVENT_ROW_SELECTION_CHANGED` events
+- Tracks single-step selection (clears when none or multiple selected)
+- Displays message when no/multiple steps are selected
+
+**Template Structure:**
+```html
+<!-- When a step is selected -->
+<cf-cplace-forms-wizard-step-editor-for-wizard-attributes step-id="...">
+  <!-- Renders Title, Description, Next attributes -->
+</cf-cplace-forms-wizard-step-editor-for-wizard-attributes>
+
+<cf-cplace-forms-wizard-step-editor step-id="...">
+  <!-- Renders type-specific editor (FormStepEditor, TableStepEditor, etc.) -->
+</cf-cplace-forms-wizard-step-editor>
+
+<!-- When no step or multiple steps selected -->
+<div>No step or multiple steps selected...</div>
+```
+
+**Sub-Components:**
+- `StepEditorForWizardAttributes.component.ts`: Fetches and renders common step attributes
+- `StepEditor.component.ts`: Loads the appropriate step-type-specific editor
+
+## Use Cases
+
+### Primary Use Case: Wizard Design & Configuration
+
+**When to use:** When designing or modifying a Forms Wizard and needing to configure individual steps.
+
+**Workflow:**
+1. User opens a Wizard page
+2. User selects a step in the Wizard Step Manager table
+3. This widget automatically displays the selected step's configuration
+4. User edits step properties (title, description, next steps, type-specific settings)
+5. User clicks Save to persist changes
+
+### Specific Scenarios
+
+1. **Creating a new wizard flow**: Configure each step's content, navigation, and behavior as you build the wizard
+2. **Modifying existing steps**: Update form fields, table columns, or decision options for existing steps
+3. **Adjusting step flow**: Change the "Next" step references to modify the wizard navigation path
+4. **Localizing wizard content**: Edit step titles and descriptions in different languages
+
+## Configuration Options
+
+### Widget Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `height` | Number | Fixed height for the widget (inherited from BASE_MIXIN) |
+
+The widget has minimal configuration as it derives most behavior from:
+- The selected step's type
+- The wizard's active state
+- User permissions
+
+### Editing Constraints
+
+The widget enforces these constraints:
+- **Read-only when wizard is active**: Cannot edit steps while the wizard is deployed
+- **Read-only without write permission**: Respects cplace permission model
+- **Single-step editing**: Only one step can be edited at a time
+
+## Relationship to Other Widgets
+
+### Widget Ecosystem on Wizard Pages
+
+The default Wizard page layout includes three complementary widgets:
+
+| Widget | Purpose |
+|--------|---------|
+| **Wizard Analysis Widget** (`cf.cplace.formsWizard.wizardAnalysis`) | Provides overview/validation of the wizard |
+| **Wizard Step Manager Widget** (`cf.cplace.formsWizard.stepManager`) | Displays/manages the list of steps (table) |
+| **Step Editor for Wizard Widget** (this widget) | Edits the currently selected step |
+
+### Interaction Pattern
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     WIZARD PAGE                              │
+├───────────────────────────────────┬─────────────────────────┤
+│  Wizard Analysis Widget           │  Wizard Activation      │
+│  (validation, statistics)         │  Widget                 │
+├───────────────────────────────────┤  (activate/deactivate)  │
+│  Wizard Step Manager Widget       │                         │
+│  (step list table)                │  Attributes Widget      │
+│         │                         │  (wizard settings)      │
+│         │ selection event         │                         │
+│         ▼                         │                         │
+│  Step Editor for Wizard Widget    │                         │
+│  (edit selected step)             │                         │
+└───────────────────────────────────┴─────────────────────────┘
+```
+
+### Related Widgets
+
+- **Step Editor Widget** (`cf.cplace.formsWizard.stepEditorWidget`): Similar functionality but embedded on Step pages directly, not Wizard pages
+- **Step Preview Widget** (`cf.cplace.formsWizard.stepPreviewWidget`): Shows how the step will appear to end users
+
+## Step Types Supported
+
+The widget supports editing for all registered step types:
+
+| Step Type | Description | Editor Component |
+|-----------|-------------|------------------|
+| Form Step | Collects data via form fields | `FormStepEditor` |
+| Table Step | Displays/edits tabular data | `TableStepEditor` |
+| Decision Step | Branching logic based on user choices | `DecisionStepEditor` |
+| Info Step | Displays informational content | `InfoStepEditor` |
+| Script Step | Executes server-side scripts | `ScriptStepEditor` |
+
+Custom step types can be registered via the `StepTypeExtension` extension point.
+
+## Technical Notes
+
+### Event Communication
+
+The widget relies on AngularJS event broadcasting:
+- **Listens for:** `StaticTableCtrl.EVENT_ROW_SELECTION_CHANGED`
+- **Responds to:** `ACTIVATION_STATE_CHANGED` (refreshes UI when wizard is activated/deactivated)
+
+### 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.wizard`
+
+### Dependencies
+
+- Requires the Wizard Step Manager widget on the same page (provides step selection)
+- Requires proper setup of step types and their configurations
+
+## Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `StepEditorForWizardWidgetDefinition.java` | Widget definition |
+| `StepEditorForWizard.component.ts` | Main frontend component |
+| `StepEditorForWizardAttributes.component.ts` | Attributes section |
+| `StepEditor.component.ts` | Type-specific editor container |
+| `WizardStepEditorController.java` | REST API for attributes |
+| `WizardStepEditorService.java` | Backend service |
+| `messages_en.properties` / `messages_de.properties` | Localization |