@cplace/test-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,238 @@
+# Widget Research: cf.cplace.layoutTabsWidget.widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.layoutTabsWidget.widget`
+**Widget Name:** Alternative Layouts as Tabs
+**Repository:** cplace-paw
+**Definition Class:** `cf.cplace.layoutTabsWidget/src/main/java/cf/cplace/layoutTabsWidget/script/LayoutTabsWidgetWidgetDefinition.java`
+
+## 1. Description
+
+The Alternative Layouts as Tabs widget displays multiple alternative page layouts as navigable tabs in a single widget. It allows users to switch between different views/layouts of the same page content through a tabbed interface, where each tab displays a different layout configuration with its own set of widgets and content organization.
+
+## 2. Purpose and Core Functionality
+
+### What This Widget Does
+
+The widget provides a tabbed navigation interface that:
+
+1. **Displays alternative layouts as tabs**: Shows multiple alternative layouts of a page type as horizontal tabs with icons and labels
+2. **Dynamic content loading**: Loads the selected layout's content dynamically via AJAX without full page reloads
+3. **Browser history integration**: Integrates with browser history and hash-based URLs, allowing users to bookmark specific tabs and use back/forward navigation
+4. **Layout selection logic**: Supports both simple static configuration and advanced programmatic selection of which layouts to show and which should be active by default
+
+### Key Technical Characteristics
+
+- **No padding/frame**: The widget renders without padding or frame (`isNoPadding() = true`, `showFrame() = false`)
+- **Dynamic content swapping**: Uses the `cplace-swappable` directive to swap content without full page reloads
+- **URL hash management**: Manages URL hash parameters to maintain tab state (format: `#widgetId=layoutInternalName`)
+- **Navigation guardians**: Integrates with cplace's navigation guardian system to prevent accidental navigation away from unsaved changes
+- **Recents tracking**: Automatically updates the user's recent items when switching tabs
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Multi-View Page Layouts**
+   - Display the same page content in different layouts (e.g., "Details" view, "Wiki" view, "Dashboard" view)
+   - Allow users to switch between comprehensive and simplified views of complex content
+   - Provide role-specific or context-specific views of the same underlying data
+
+2. **Organized Content Presentation**
+   - Group related widgets into different tabs to reduce visual clutter on a single page
+   - Separate different aspects of an entity (e.g., "Overview", "Timeline", "Documents", "Comments")
+   - Create focused work contexts within a single page
+
+3. **Conditional Layout Display**
+   - Show different layouts based on user permissions or roles (e.g., admin view vs. user view)
+   - Display layouts conditionally based on page properties or current user context
+   - Dynamically adjust available tabs based on business logic
+
+4. **Space-Efficient Design**
+   - Maximize screen real estate by organizing content vertically into tabs rather than requiring long scrolling pages
+   - Provide quick access to multiple views without requiring navigation to separate pages
+
+### Example Scenarios
+
+- **Project Management**: Tabs for "Overview", "Tasks", "Timeline", "Budget", "Resources"
+- **Document Management**: Tabs for "Metadata", "Content", "Versions", "Permissions", "Audit Log"
+- **User Profiles**: Tabs for "Personal Info", "Activity", "Projects", "Settings"
+- **Dashboard Pages**: Tabs for different KPI categories or time ranges
+
+## 4. Configuration Options
+
+The widget provides two configuration modes via attribute grouping:
+
+### 4.1 Basic Configuration (Simple Layout Selection)
+
+**Attribute Group:** `simpleLayoutSelection`
+
+**Configuration Attributes:**
+- **Layouts to show** (`layouts`): Multi-select enumeration of alternative layouts to display as tabs
+- **Active Layout** (`layoutSelection`): Single-select enumeration to specify which layout should be shown initially
+
+**Use Case:** Static configuration where the set of tabs and default active tab are fixed and don't need to change based on context.
+
+### 4.2 Advanced Configuration (Script-Based Layout Selection)
+
+**Attribute Group:** `advancedLayoutSelection`
+
+**Configuration Attributes:**
+- **Preselected layouts to show** (`advancedLayouts`): Starting set of layouts to show (used as input to script)
+- **Preselected active layout** (`advancedLayoutSelection`): Starting active layout (used as input to script)
+- **Layout Selection Script** (`cplacejsLayouts`): cplace.js script that dynamically determines which layouts to show and which should be active
+
+**Script Bindings:**
+- `page` / `embeddingPage`: The page on which the widget is displayed (WrappedPage object)
+- `selectedLayouts`: Array of internal layout names from the preselection (can be modified)
+- `selectedActiveLayout`: Internal name of the preselected active layout (can be changed)
+
+**Script Return Value:**
+```javascript
+{
+    "layouts": ["layout1", "layout2", "layout3"],  // Array of internal layout names to show as tabs
+    "active": "layout2"                             // Internal name of the layout to show initially
+}
+```
+
+**Example Script Use Cases:**
+- Filter layouts based on current user's role or permissions
+- Show/hide tabs based on page attribute values or state
+- Change the default active tab based on user preferences or context
+- Conditionally display layouts based on search results or related entities
+
+**Default Script Template:**
+```javascript
+var layoutConfig = {
+    layouts: selectedLayouts,
+    active: selectedActiveLayout
+};
+
+return layoutConfig;
+```
+
+### 4.3 Configuration Constraints
+
+- **Recursive nesting prevention**: A layout displayed in the tabs widget cannot itself contain another Alternative Layouts as Tabs widget (validation error: "The selected layout must not contain the Alternative Layouts as Tabs Widget")
+- **Alternative layouts only**: Only works with alternative layouts of the page's type definition, not the default layout
+- **Minimum one layout**: At least one valid layout must be configured for the widget to be complete
+
+## 5. Technical Implementation Details
+
+### Frontend Components
+
+**TypeScript Directive:** `cfCplaceLayoutTabsWidget.ts`
+- Controller: `LayoutTabsCtrl`
+- Template: `layoutTabsWidgetWidgetDefinition.htm`
+- Creates tab navigation UI using Bootstrap tabs (`nav nav-tabs`)
+- Manages browser history state and hash-based routing
+- Handles content swapping via AJAX requests
+
+**Key Frontend Features:**
+- **Tab tooltips**: Displays internal layout name as tooltip when multiple layouts have the same display name
+- **Hash change detection**: Listens to browser hash changes to update content when URLs are directly accessed or back/forward buttons are used
+- **Event system**:
+  - Emits `cf.cplace.layoutTabsWidget.switchTab` event when tab switching is requested
+  - Emits `cf.cplace.layoutTabsWidget.tabSwitched` event after tab content is loaded
+- **Navigation confirmation**: Prompts user if there are unsaved changes before switching tabs
+
+### Backend Components
+
+**Handler:** `LoadLayoutContentHandler`
+- Loads and renders the content of the selected alternative layout
+- Creates a dummy widget container to render the layout's widgets
+- Updates user's recent items history with the selected tab
+- Validates that the layout doesn't recursively contain the tabs widget
+
+**Widget Definition:** `LayoutTabsWidgetWidgetDefinition`
+- Configuration type: Uses attribute grouping to switch between basic and advanced modes
+- Validates configuration completeness based on selected grouping mode
+- Provides widget state data to frontend (layouts, active layout, load URL, widget ID)
+
+### Layout Selection Implementations
+
+**SimpleLayoutSelectionAttributeGroup:**
+- Directly returns the configured layouts and active selection
+- No script evaluation needed
+- Used for static, unchanging tab configurations
+
+**AdvancedLayoutSelectionAttributeGroup:**
+- Evaluates the cplace.js script in a sandboxed engine
+- Provides bindings for page and preselected values
+- Allows full programmatic control over layout selection
+- Falls back to preselection if script returns null/undefined
+
+## 6. Related Components and Context
+
+### Dependencies
+
+- **Platform Plugin**: Part of the core platform (dependency on `cf.cplace.platform`)
+- **Alternative Layouts System**: Relies on cplace's type definition layout system
+- **Widget Framework**: Extends standard `WidgetDefinition` base class
+- **cplace.js Engine**: Advanced mode uses cplace.js scripting capabilities
+
+### Related Widgets
+
+- **Standard Layout Widgets**: The content displayed in each tab consists of standard cplace widgets (search tables, forms, embedded content, etc.)
+- **Embedded Search Widget**: Commonly used within tab layouts to display filtered entity lists
+- **Form Widgets**: Often used to show entity details in different arrangements
+
+### Integration Points
+
+1. **Type Definition Layouts**: Works exclusively with alternative layouts defined on page types
+2. **Browser History**: Deep integration with HTML5 history API and pjax for smooth navigation
+3. **URL Routing**: Uses hash fragments to encode tab state in URLs for bookmarking and sharing
+4. **Navigation Guardians**: Respects cplace's navigation protection system for unsaved changes
+5. **Recents Tracking**: Automatically tracks tab visits in user's recent items
+
+### Limitations and Considerations
+
+1. **No recursive nesting**: Cannot place a tabs widget inside a layout that is displayed in another tabs widget
+2. **Alternative layouts only**: Cannot use the default layout as one of the tabs
+3. **Single widget per page**: URL hash format suggests one tabs widget per page for proper URL state management (though technically multiple could exist)
+4. **Page context only**: Advanced scripting mode only works when widget is embedded in a Page, not in TypeDefinition or TypeDefinitionLayout contexts
+5. **Performance**: Each tab switch triggers an AJAX request to load content, so complex layouts may have noticeable load times
+
+## 7. Development and Testing
+
+### Test Coverage
+
+The plugin includes several test types:
+
+1. **Unit Tests**: `LoadLayoutContentHandlerTest.java` - Tests content loading with various permission scenarios
+2. **E2E Test Data**:
+   - `tabs-as-links/`: Tests tab navigation and linking behavior
+   - `grouped-attributes/`: Tests attribute grouping configuration
+   - `cke5-alternative-tab-layout/`: Tests rich text editor integration within tabs
+
+### Key Test Scenarios
+
+- Loading tab content for users with read permissions but no workspace access
+- Validation that nested tabs widgets are rejected
+- Tab switching with navigation guardians active
+- URL hash-based tab selection and browser navigation
+
+## 8. Internationalization
+
+The widget supports multiple languages with message bundles:
+- English: `messages_en.properties`
+- German: `messages_de.properties`
+
+Key translatable elements:
+- Widget name: "Alternative Layouts as Tabs" / "Alternative Layouts als Tabs"
+- Configuration attribute labels and help texts
+- Error messages
+- Tab-related UI text
+
+## 9. Summary
+
+The Alternative Layouts as Tabs widget is a sophisticated navigation and content organization tool that enables:
+
+- **Multi-view presentation**: Display the same page in different layouts accessible via tabs
+- **Dynamic configuration**: Static or script-based selection of which tabs to show
+- **Seamless navigation**: Browser history integration and AJAX-based content loading
+- **Context-aware display**: Conditional tab visibility based on user, permissions, or page state
+- **User experience optimization**: Reduces page clutter and improves content organization
+
+This widget is ideal for complex pages that need to present information in multiple ways or group related content into organized sections without requiring users to navigate to separate pages.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-lowCodeWidgets-lowCodeButton/research.md

@@ -0,0 +1,272 @@
+# Low-Code Button Widget Research
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.lowCodeWidgets.lowCodeButton`
+**Widget Name:** Low-Code Button
+**Repository:** `cplace-paw`
+**Definition Class:** `cf.cplace.lowCodeWidgets.script.LowCodeButtonWidgetDefinition`
+
+### Purpose (1-2 Sentence Description)
+
+The Low-Code Button widget displays a customizable button that executes a JavaScript-based Low-Code script when clicked, enabling users to automate business logic and actions directly from the page interface. It provides access to page data, search results, and table selections as script bindings, and can execute scripts either synchronously or asynchronously as background jobs.
+
+---
+
+## Conceptual Documentation
+
+### Core Functionality
+
+The Low-Code Button widget is an interactive widget that allows administrators and low-code developers to embed custom automation logic into cplace pages through a button interface. When clicked, the button executes a configurable JavaScript script that has access to contextual data from the page, connected widgets, and data sources.
+
+### Use Cases
+
+#### 1. **Data Processing and Transformation**
+Execute custom business logic to process or transform data on the current page or related entities. For example:
+- Calculate and update aggregate values across multiple pages
+- Transform data formats or structures
+- Apply custom validation rules
+- Generate derived data based on complex business rules
+
+#### 2. **Bulk Operations on Selected Items**
+Perform actions on multiple items selected in a connected table widget:
+- Bulk update attributes across selected pages
+- Mass approve/reject workflow items
+- Batch delete or archive records
+- Apply consistent changes to a selection of entities
+
+#### 3. **External System Integration**
+Trigger integrations with external systems or services:
+- Call external APIs to synchronize data
+- Send notifications to external systems
+- Export data to external formats
+- Import data from external sources
+
+#### 4. **Workflow and Process Automation**
+Automate workflow steps and business processes:
+- Trigger state transitions
+- Start background jobs for long-running processes
+- Execute multi-step approval processes
+- Orchestrate complex business workflows
+
+#### 5. **Report Generation and Data Export**
+Generate custom reports or export data:
+- Create formatted reports based on search results
+- Export data in custom formats
+- Generate summary statistics
+- Create audit logs or change histories
+
+#### 6. **User Interaction with Confirmation**
+Present users with action buttons that require confirmation:
+- Delete operations requiring user confirmation
+- Critical actions that need explicit approval
+- Operations that collect additional input before execution
+
+---
+
+## Configuration Concepts
+
+### Script Structure
+
+The widget requires a Low-Code JavaScript script that returns an object with two methods:
+
+1. **`checkAccess()`**: Determines whether the button should be enabled for the current user
+   - Returns `true` to enable the button, `false` to disable it
+   - Evaluated when the page loads to control button visibility/state
+   - Does not have access to the `log` binding
+
+2. **`call()`**: Contains the actual business logic executed when the button is clicked
+   - Can optionally return a success message (string, localized string, or object with `message` property)
+   - Can return a job ID if starting a background job
+   - Has access to all script bindings including the `log` binding for user output
+
+### Script Bindings
+
+The script has access to the following bindings:
+
+| Binding | Type | Description |
+|---------|------|-------------|
+| `pages` | `Iterable<WrappedPage>` | Pages from the configured data source (search, selection, or connected table) |
+| `searchResults` | `Iterable<WrappedCustomEntity<?>>` | All search results (if "Include All Search Results" is enabled) |
+| `embeddingPage` | `WrappedPage` | The page on which the widget is embedded |
+| `additionalData` | `WrappedPage` | Data collected from an additional data dialog (if configured) |
+| `log` | `LowCodeButtonScriptExecutionLogger` | Logger for outputting text or HTML during script execution (only in `call()`) |
+| `messages` | `CplaceJSTypeMessageProvider` | Access to internationalized messages defined in the embedding page's type definition |
+
+### Main Configuration Options
+
+#### 1. **Button Appearance**
+- **Button Label**: Customizable localized text for the button (defaults to "Execute Script")
+- **Button Class**: Bootstrap CSS class for styling (Primary, Secondary, Success, Danger, Warning, Info, Light, Dark)
+- **Show Frame**: Option to display the widget within a frame
+
+#### 2. **Script Configuration**
+- **Script**: The Low-Code JavaScript that defines the button's behavior
+- **Execute Synchronously**: Controls whether the script runs synchronously (default: asynchronous background job)
+  - Asynchronous: Suitable for long-running operations, displays job status and logs
+  - Synchronous: Immediate execution, limited to default script timeout (60 seconds)
+
+#### 3. **Data Source Options**
+Multiple ways to provide data to the script:
+
+- **Search**: Define a search query whose results are available as the `pages` binding
+- **Connected Table**: Connect to a table widget on the same page
+  - **Selection Only**: Only selected rows from the table are available
+  - Can also connect to nested connected tables
+- **Selection**: Manually select specific pages to provide as the `pages` binding
+- **Include All Search Results**: Provides raw search results (not just pages) in the `searchResults` binding
+
+#### 4. **User Interaction Options**
+
+**Confirmation Dialog:**
+- **Show Confirmation Dialog**: Prompts user before script execution
+- **Confirmation Dialog Text**: Customizable message text
+- **Confirmation/Cancel Button Labels**: Customizable button labels
+
+**Additional Data Collection:**
+- **Additional Data Type**: Select a cplace type for collecting input before execution
+- **Additional Data Attributes**: Specify which attributes to display in the dialog
+- **Additional Data Dialog Title**: Customize the dialog title
+
+### Execution Flow
+
+1. **Button Render**: Page loads, `checkAccess()` is evaluated to determine if button should be enabled
+2. **Button Click**: User clicks the button
+3. **Confirmation** (optional): If configured, user confirms the action
+4. **Additional Data** (optional): If configured, user provides additional data through a dialog
+5. **Script Execution**: The `call()` method is executed
+   - Asynchronous: Job is created and runs in background, user can monitor progress
+   - Synchronous: Script executes immediately, user waits for completion
+6. **Result Display**: Success or error message is shown to the user
+
+### Permissions and Access Control
+
+- **Embedding Permission**: Only users with "Low-Code permission" (`GlobalPermissions.mayEditLowCode()`) can embed this widget
+- **Script Editing**: The script attribute is only visible/editable to users with Low-Code permission
+- **Runtime Access Control**: The `checkAccess()` method provides dynamic access control based on context
+
+### Integration with Other Widgets
+
+The Low-Code Button widget can be:
+- **Embedded in**: Attribute Group widgets or Connected Attribute Group widgets
+- **Connected to**: Embedded Search as Table widgets (to access selected rows)
+- **Nested**: Can work with connected tables that are themselves connected to other tables
+
+---
+
+## Related Concepts
+
+### Comparison with Low-Code Text Widget
+
+The Low-Code Button is part of a family of Low-Code widgets:
+- **Low-Code Button**: Executes actions when clicked (imperative, user-triggered)
+- **Low-Code Text Widget**: Displays computed text/HTML (declarative, auto-updated)
+
+Both share similar data source configurations and script bindings, but serve different purposes.
+
+### Job Execution
+
+When executed asynchronously (default):
+- A background job is created and tracked
+- Users receive a link to monitor job progress
+- Script output via `log.logText()` and `log.logHtml()` is captured in the job log
+- Suitable for long-running operations
+
+When executed synchronously:
+- Script runs in the current request context
+- Limited to default script timeout (typically 60 seconds)
+- Log output is not displayed to the user
+- Suitable for quick operations that need immediate feedback
+
+### Low-Code Script Engine
+
+The widget uses the cplace Low-Code script engine with:
+- **Sandboxed execution**: Scripts run in a controlled environment
+- **Type safety**: Access to typed wrappers for cplace entities
+- **Action support**: Can perform cplace actions (create/update/delete pages) when enabled
+- **Termination support**: Long-running scripts can be terminated
+- **Error handling**: Comprehensive error messages and stack traces
+
+---
+
+## Technical Details
+
+### Key Classes
+
+- **Definition**: `cf.cplace.lowCodeWidgets.script.LowCodeButtonWidgetDefinition` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/script/LowCodeButtonWidgetDefinition.java:52)
+- **Execution**: `cf.cplace.lowCodeWidgets.utils.LowCodeButtonScriptExecutionProcessor` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/utils/LowCodeButtonScriptExecutionProcessor.java:36)
+- **Handlers**:
+  - `StartScriptExecutionHandler` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/handler/StartScriptExecutionHandler.java:16)
+  - `ExecuteScriptHandler` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/handler/ExecuteScriptHandler.java:35)
+  - `ConfirmScriptExecutionHandler` (optional confirmation step)
+  - `GetAdditionalDataHandler` (optional data collection step)
+
+### Frontend Components
+
+- **Controller**: `LowCodeButtonWidgetCtrl` (TypeScript)
+- **Directive**: `lowCodeButtonWidgetDirective`
+- **Features**:
+  - Listens to table row selection events
+  - Submits table selection state to backend
+  - Handles nested connected table selections
+  - Manages event listeners lifecycle
+
+### Configuration Type
+
+Defined in `LowCodeWidgetsWidgetTypes.LOW_CODE_BUTTON_WIDGET` with attributes:
+- Script, button label, button class
+- Data source grouping (search/table/selection)
+- Confirmation dialog settings
+- Additional data type and attributes
+- Execution mode (sync/async)
+- Frame display option
+
+---
+
+## Example Script Structure
+
+```javascript
+return {
+    // Check if the current user should have access to execute this button
+    checkAccess: function() {
+        // Example: Only enable if embedding page has a specific status
+        return embeddingPage.get('cf.cplace.status') === 'Active';
+    },
+
+    // Execute the actual business logic
+    call: function() {
+        log.logText('Starting Low-Code button script execution');
+
+        // Process all pages from the data source
+        pages.forEach(function(page) {
+            // Perform operations on each page
+            page.set('cf.cplace.lastProcessed', new Date());
+            page.save();
+            log.logHtml('<p>Processed page: ' + page.getName() + '</p>');
+        });
+
+        // Return a localized success message
+        return {
+            message: {
+                de: 'Erfolgreich verarbeitet',
+                en: 'Successfully processed'
+            }
+        };
+    }
+};
+```
+
+---
+
+## Prerequisites and Dependencies
+
+1. **User Permissions**: Users must have Low-Code permission to configure the widget
+2. **Embedding Context**: Must be embedded on a page or within an attribute group widget
+3. **Data Source**: At least one data source should be configured (search, table, or selection) if the script needs to access pages
+4. **Script Knowledge**: Requires understanding of cplace Low-Code JavaScript API
+
+---
+
+## Summary
+
+The Low-Code Button widget is a powerful tool for embedding custom automation and business logic directly into cplace pages. It bridges the gap between no-code page building and full custom development by providing a scriptable button interface with rich access to page data, search results, and user selections. Its flexibility in data sources, execution modes, and user interaction options makes it suitable for a wide range of automation scenarios, from simple bulk operations to complex multi-step workflows.