@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,193 @@
+# Widget Research: cf.cplace.simpleForm.widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.simpleForm.widget`
+**Widget Name:** Creation Form
+**Repository:** cplace-paw
+**Icon:** cf-pencil-group
+
+### Short Description
+
+The Simple Form widget provides an embedded creation form that allows users to quickly create multiple instances of a specific page type without leaving the current page context.
+
+## Purpose
+
+The Simple Form widget is designed to streamline the process of creating multiple related pages. Instead of navigating away to create new pages individually, users can configure a widget that displays a creation form directly embedded in the current page. After submitting the form, it automatically resets to allow immediate creation of the next instance.
+
+**Key characteristics:**
+- Always displays in edit mode (always editable)
+- Automatically resets after successful submission
+- Can preset reference attributes to link created pages to the embedding page
+- Supports custom layouts for attribute arrangement
+
+## Use Cases
+
+### 1. Rapid Data Entry
+When users need to create many instances of the same type in succession, such as:
+- Creating multiple tasks within a project page
+- Adding multiple risk items to a risk register
+- Logging multiple issues or incidents
+- Entering a series of related records (e.g., meeting minutes, action items)
+
+### 2. Contextual Page Creation
+Creating pages that are automatically linked to the current context:
+- A project page with a form to create tasks that are automatically linked to that project
+- A parent entity with a form to create child entities
+- A workflow stage with a form to create items in that stage
+
+### 3. Simplified User Experience
+Reducing navigation complexity for non-technical users:
+- Providing a focused creation interface without the full page creation workflow
+- Hiding complexity by showing only relevant attributes in the form
+- Maintaining user context by keeping them on the same page
+
+### 4. Embedded Creation Workflows
+Supporting specific business processes:
+- Feedback collection forms
+- Quick entry forms for repetitive data
+- Intake forms for requests or submissions
+- Data collection interfaces embedded in dashboards
+
+## Configuration Concepts
+
+The Simple Form widget is configured through several key settings:
+
+### Core Configuration
+
+1. **Type to Create** (`FORM_TYPE_NAME`)
+   - Specifies which page type the form will create
+   - Required field
+   - Dynamically populated based on types available in the current space
+
+2. **Reference to Embedding Page** (`ATTRIBUTE_MATCHING_EMBEDDED`)
+   - Optional attribute that automatically links created pages to the embedding page
+   - When configured, the specified reference attribute is automatically populated
+   - Useful for parent-child relationships
+   - The widget checks permissions considering this preset value
+
+3. **Attributes Layout** (`LAYOUT`)
+   - Controls which attributes are displayed and how they are arranged
+   - Can be configured only after selecting a type
+   - Uses nested "Attribute in Form" widgets to specify individual attributes
+   - Allows customization of which fields appear in the creation form
+
+### Display Options
+
+4. **Title** (`TITLE`)
+   - Optional localized string for the widget title
+   - Displayed in the widget frame if frame is enabled
+
+5. **Show Widget Frame** (`SHOW_FRAME`)
+   - Boolean option to show/hide the widget frame
+   - Defaults to true
+
+6. **Single Column** (`SINGLE_COLUMN`)
+   - Boolean option to display form attributes in a single column
+   - Defaults to false (two-column layout)
+
+7. **Disable Autofocus** (`DISABLE_AUTO_FOCUS`)
+   - Boolean option to prevent automatic focus on the first form field
+   - Defaults to false
+
+8. **Height** (`HEIGHT`)
+   - Fixed height for the widget
+   - Optional numeric value
+
+### Permission Handling
+
+The widget performs permission checks before displaying the form:
+- Verifies that the current user has rights to create pages of the specified type
+- Checks creation permissions in the context of the specified space
+- If an attribute matching embedded is configured, validates that the user can create pages with that reference preset
+- If the user lacks permissions, the form is not displayed
+
+## Form Behavior
+
+### Submission Flow
+
+1. User fills out the form with attributes defined in the layout
+2. User clicks "Create and continue" button
+3. System validates the input
+4. Page is created with:
+   - The specified type
+   - Attributes set by the user
+   - Reference to embedding page (if configured)
+   - Location in the same space as the embedding page
+5. Success message is shown: "Successfully created [Type] [Name]"
+6. Form is automatically reset to a new empty state
+7. All widgets on the page are reloaded to reflect the new data
+
+### Button Labels
+
+- **Submit button:** "Create and continue" (instead of standard "Save")
+- **Reset button:** "Reset" (instead of standard "Cancel")
+
+This naming emphasizes the continuous creation workflow.
+
+## Related Components
+
+### Attribute in Form Widget
+
+**Widget ID:** `cf.cplace.simpleForm.attributeInForm`
+
+This is a companion widget that can only be embedded inside the Simple Form widget. It is used within the layout configuration to specify individual attributes that should be displayed in the form.
+
+**Configuration:**
+- Attribute name selection (from the target type)
+- Automatically inherits display settings from the parent form (single column, autofocus)
+
+**Purpose:**
+- Provides granular control over which attributes appear in the form
+- Allows ordering of attributes
+- Enables selective display of only relevant attributes
+
+## Technical Context
+
+### Dependencies
+
+The Simple Form widget relies on several platform components:
+- Edit mode rendering system (EditableBlockSubstitution)
+- Page creation and validation framework
+- Widget layout system for embedding child widgets
+- Permission system for creation rights checking
+- Type definition system for attribute metadata
+
+### Integration Points
+
+1. **Permission System:**
+   - Checks `sessionUserMayCreatePage()` before rendering the form
+   - Validates through the standard page creation URL mechanism
+
+2. **Widget Layout System:**
+   - Implements `IWidgetDefinitionWithLayout` to support nested widgets
+   - Uses `DummyWidgetContainer` to manage the form state
+   - Leverages `LayoutConstraint` for attribute layout configuration
+
+3. **Form Submission:**
+   - Uses `SubmitSimpleFormHandler` for processing form submissions
+   - Integrates with standard editable block submission flow
+   - Triggers widget reload after successful creation
+
+### Design Patterns
+
+- **Dummy Entity Pattern:** Creates a temporary "dummy" page object for form editing that hasn't been persisted yet
+- **Editable Block Pattern:** Reuses the standard editable block infrastructure for form rendering
+- **Handler-based Submission:** Uses dedicated handler for form processing and post-submission logic
+- **Automatic Reset:** After creation, replaces the persisted entity with a fresh dummy for the next creation
+
+## Comparison with Standard Page Creation
+
+| Aspect | Simple Form Widget | Standard Page Creation |
+|--------|-------------------|----------------------|
+| Navigation | Stays on same page | Navigates to creation form |
+| Workflow | Optimized for multiple creations | One at a time |
+| Context | Preserves current page context | New page context |
+| Customization | Configurable attribute subset | All attributes shown |
+| Linking | Automatic reference to embedding page | Manual relationship setup |
+| Button Labels | "Create and continue" | "Save" |
+| After Save | Form resets for next entry | Navigates to created page |
+
+## Summary
+
+The Simple Form widget is a productivity tool designed for scenarios where users need to create multiple related pages efficiently. It transforms the typically disruptive page creation process into a streamlined, embedded workflow that maintains user context and accelerates repetitive data entry tasks. The widget is particularly valuable in parent-child relationship scenarios where created pages should automatically reference their context, and when only a subset of attributes needs to be filled during creation.

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

@@ -0,0 +1,311 @@
+# Table Detail View Widget Research
+
+## Widget Information
+
+- **Widget ID**: `cf.cplace.tableDetailViewWidget.widget`
+- **Widget Name**: Page Details
+- **Repository**: `cplace-paw`
+- **Definition Class**: `cf.cplace.tableDetailViewWidget/src/main/java/cf/cplace/tableDetailViewWidget/script/TableDetailViewWidgetDefinition.java`
+
+## Purpose
+
+### What This Widget Does
+
+The Table Detail View Widget provides a dynamic detail panel that displays selected attributes of a page chosen from a connected table widget. It creates a master-detail interface where selecting a row in a table dynamically updates the detail view to show that row's attributes.
+
+**One-sentence description**: The Table Detail View Widget displays selected attributes of a table row in a detail panel that updates dynamically when users click on different table entries.
+
+**Extended description**: The Table Detail View Widget creates a synchronized relationship with a table widget, listening for row selection events and dynamically displaying a configurable set of attributes for the selected page in a structured detail view layout with an optional header.
+
+## Core Concepts
+
+### Master-Detail Pattern
+
+This widget implements the classic **master-detail UI pattern**:
+
+- **Master**: A table widget showing multiple rows of data
+- **Detail**: This widget showing detailed attributes of the selected row
+- **Synchronization**: Automatic updates when the user selects a different row
+
+The widget acts as a "detail pane" companion to any table widget on the same page.
+
+### Key Terminology
+
+- **Table Widget**: The master table that displays a list of pages (required companion widget)
+- **Selected Entry**: The page/row that is currently selected in the table
+- **Detail View**: The panel showing attributes of the selected entry
+- **Header**: Optional rich text content displayed above the detail attributes
+- **Connected Table**: The table widget this detail view is linked to (via widget ID)
+
+### How It Works
+
+1. **Initial Load**:
+   - If no row is selected, shows the first entry from the connected table's search results
+   - Displays the configured attributes of that first entry
+
+2. **Row Selection**:
+   - Listens for `FlexiCellCtrl.EVENT_CELL_SELECTED` events from the table widget
+   - When a row is clicked in the connected table, the detail view updates via AJAX
+   - Loads and displays the attributes of the newly selected page
+
+3. **Display Layout**:
+   - Optional header section (rich text)
+   - Attributes displayed in a 3-column layout
+   - Each attribute shown with its label and value
+
+## Use Cases
+
+### When to Use This Widget
+
+1. **Space-Constrained Table Views**
+   - When a table has many columns that don't all fit comfortably on screen
+   - Show key columns in the table, detailed attributes in the detail panel
+   - Example: A list of projects showing only name and status in the table, with full details (description, dates, owner, budget, etc.) in the detail panel
+
+2. **Read-Only Detail Information**
+   - Displaying additional context about a selected item without editing
+   - When users need to review details but not modify them
+   - Example: Viewing full specifications of a product selected from a product catalog table
+
+3. **Dashboard and Reporting Layouts**
+   - Creating dashboard pages with table + detail layouts
+   - Master-detail reports where the table provides overview and the detail provides depth
+   - Example: Risk register showing all risks in a table, with detailed risk assessment shown when a risk is selected
+
+4. **Improved User Experience**
+   - Avoiding navigation away from the current page to see details
+   - Keeping users in context while browsing list data
+   - Quick preview of full information without opening separate pages
+   - Example: Task list where selecting a task shows its full description and metadata
+
+5. **Structured Information Display**
+   - Showing related but categorized information
+   - When details are too verbose for table columns but important to have readily accessible
+   - Example: Incident management where the table shows incident titles and status, detail shows full description, timestamps, and involved parties
+
+### Problem This Widget Solves
+
+The widget solves the problem of displaying **detailed information from tables without overwhelming the table view or requiring navigation**. It addresses:
+
+- **Limited horizontal space**: Tables with many columns become unwieldy
+- **Information density**: Users need both overview (table) and details
+- **Navigation overhead**: Opening individual pages disrupts workflow
+- **Context switching**: Users want to browse multiple items quickly
+
+It provides a **responsive detail panel** that keeps users on the same page while exploring data.
+
+## Configuration Concepts
+
+### Main Configuration Options
+
+#### 1. Table Widget ID
+- **Configuration**: `TABLE_WIDGET_ID` (inherited from `ABSTRACT_CONNECTED_TABLE_WIDGET`)
+- **Purpose**: Specifies which table widget this detail view is connected to
+- **Requirements**:
+  - Must reference a valid table widget on the same page
+  - The referenced table must have search results (pages to display)
+- **Behavior**: Determines which table's selection events to listen to
+
+#### 2. Header
+- **Configuration**: `HEADER` (Rich String attribute)
+- **Purpose**: Optional header content displayed above the detail attributes
+- **Type**: Rich text (can include formatting, links, images)
+- **Use cases**:
+  - Contextual instructions for the detail view
+  - Title or description of what the detail panel shows
+  - Static content that doesn't change with selection
+
+#### 3. Attributes
+- **Configuration**: `ATTRIBUTES` (Multi Dynamic Enumeration)
+- **Purpose**: Selects which attributes of the selected page should be displayed in the detail view
+- **Behavior**:
+  - Dynamically populated based on the table widget's type
+  - Uses `AttributesFromConnectedTableEnumerationProvider` to get available attributes
+  - Attributes are displayed in a 3-column layout
+  - At least one attribute must be selected
+- **Column Distribution**: Attributes are distributed across 3 columns using modulo logic (column = index % 3)
+
+### Configuration Workflow
+
+1. **Add the widget** to a page that already has a table widget
+2. **Select the table widget** from the TABLE_WIDGET_ID dropdown
+3. **Save the configuration** (attributes list will populate after save)
+4. **Select attributes** to display in the detail view
+5. **Optionally add header content** for context
+6. **Save** to activate the detail view
+
+### Display Modes
+
+The widget has a simple display mode:
+
+- **3-Column Layout**: Attributes are automatically distributed across 3 columns
+- **Show in one column**: Each attribute shown with `showInOneColumn="true"` parameter
+- **Label display**: Standard cplace attribute rendering with labels
+- **Read-only**: Attributes are displayed without in-place editing (`noInPlaceEditing`)
+
+## Context and Dependencies
+
+### Related Widgets
+
+The Table Detail View Widget is part of cplace's ecosystem of connected widgets:
+
+1. **Table Widget** (`cf.cplace.platform.tableWidget`)
+   - **Relationship**: Required companion widget (master)
+   - **Use together**: Table provides the list, this widget provides the details
+
+2. **Embedded Search as Table** (`cf.platform.embeddedSearchAsTable`)
+   - **Relationship**: Can be used as the master table
+   - **Use together**: Search results in table + details of selected result
+
+3. **Tuples Widget** (`cf.cplace.tuplesWidget.widget`)
+   - **Comparison**: Tuples widget has inline editing, this is read-only details
+   - **Different use case**: Tuples for editing collections, this for viewing details
+
+4. **Connected Attributes Group** (`cf.cplace.platform.connectedAttributesGroup`)
+   - **Comparison**: Shows attributes of a fixed reference, this shows attributes of dynamically selected table row
+   - **Different use case**: Connected Attributes for static 1-to-1 relationships
+
+### Key Differences from Other Widgets
+
+**vs. Tuples Widget**:
+- Table Detail View: Read-only, selection-driven detail display
+- Tuples Widget: Editable table with CRUD operations on references
+
+**vs. Connected Attributes Group**:
+- Table Detail View: Dynamic selection from table, shows details of selected item
+- Connected Attributes: Static reference, always shows the same referenced entity
+
+**vs. Attributes Widget**:
+- Table Detail View: Shows attributes of a page selected from a table
+- Attributes Widget: Shows attributes of the current page (embedding page)
+
+### Prerequisites
+
+1. **Required Widgets**:
+   - A table widget must exist on the same page
+   - The table widget must have a valid search configuration returning pages
+
+2. **Data Model Requirements**:
+   - The pages returned by the table's search must have attributes to display
+   - Attributes should be readable by the user
+
+3. **Permission Requirements**:
+   - Read access to the pages shown in the table
+   - Read access to the attributes configured for display
+
+4. **Embedding Context**:
+   - Must be embedded in a Page
+   - Must be on the same page as the table widget it references
+
+### Technical Integration
+
+#### Event-Driven Architecture
+
+The widget uses **Angular event bus** for synchronization:
+
+```
+Table Widget → FlexiCellCtrl.EVENT_CELL_SELECTED → Table Detail View Widget
+```
+
+- **Event**: `FlexiCellCtrl.EVENT_CELL_SELECTED`
+- **Trigger**: User clicks a row in the table
+- **Payload**: `selectedCell` object containing the selected page's UID
+- **Matching**: Events are matched by `componentIdentifier` to ensure the correct table-detail pair
+
+#### AJAX Loading
+
+The widget uses **dynamic content loading**:
+
+1. Initial page load renders a placeholder with the widget state
+2. JavaScript directive (`cf-cplace-table-detail-view-widget`) takes over
+3. Makes AJAX POST to `LoadHandler` with the selected page UID
+4. Server returns rendered HTML for the selected page's attributes
+5. HTML is injected into the placeholder
+6. Process repeats on each table row selection
+
+#### Three-Column Layout
+
+The `ObjectFunctions.cf_cplace_tableDetailViewWidget_showWidgets` method implements the 3-column distribution:
+
+- Creates 3 `PageAndWcAndColumn` objects (column 0, 1, 2)
+- Each column template loops through attributes where `index % 3 == column`
+- Ensures even distribution of attributes across columns
+
+## Technical Implementation Notes
+
+### Widget Architecture
+
+1. **Backend Components**:
+   - `TableDetailViewWidgetDefinition.java`: Widget definition and configuration (line 23-96)
+   - `TableDetailViewWidgetTypes.java`: Type definitions for HEADER, TABLE_WIDGET_ID, ATTRIBUTES (line 22-48)
+   - `LoadHandler.java`: AJAX handler for loading/reloading detail content (line 22-85)
+   - `ObjectFunctions.java`: Template functions for rendering attributes in columns (line 15-53)
+   - `PageAndWcAndColumn.java`: Data transfer object for page + widget config + column number (line 6-19)
+
+2. **Frontend Components**:
+   - `directive.ts`: Angular directive for event listening and AJAX updates (line 12-43)
+   - `app.ts`: Module registration
+   - Template: `tableDetailViewWidgetDefinition.htm` (shows header and directive placeholder)
+
+3. **Rendering Flow**:
+   - Main template shows header and creates directive element with state
+   - Directive initializes, calls LoadHandler with no UID (gets first result)
+   - User clicks table row → event fires → directive calls LoadHandler with UID
+   - LoadHandler returns 3 columns of attributes
+   - Template `cf_cplace_tableDetailViewWidget_showWidgets.htm` renders each column
+
+### Key Implementation Details
+
+1. **Default Selection**:
+   - If no UID is provided, queries the connected table's search
+   - Uses `search.find(1, 1)` to get the first result
+   - Displays that first result's attributes initially (LoadHandler.java:73-80)
+
+2. **Attribute Enumeration**:
+   - Extends `AbstractConnectedWidgetAttributeEnumerationProvider`
+   - Dynamically provides available attributes based on the selected table's type
+   - Ensures only valid attributes from the table's result type are selectable
+
+3. **Column Distribution Algorithm**:
+   - Iterates through selected attributes (ObjectFunctions.java:32-44)
+   - Uses `index++ % 3 == column` to assign to column 0, 1, or 2
+   - Each column rendered separately in the template
+
+4. **State Management**:
+   - Widget state stored in `data-cf-cplace-table-detail-view-widget` attribute
+   - Contains: `loadUrl`, `tableWidgetId`, `componentIdentifier`
+   - Angular directive parses and uses this state (directive.ts:17)
+
+### Limitations
+
+1. **Read-Only**:
+   - Attributes are displayed with `noInPlaceEditing` flag
+   - No editing capabilities in the detail view
+
+2. **Fixed Layout**:
+   - Always uses 3-column layout
+   - No configuration for 1, 2, or 4 columns
+
+3. **Single Selection**:
+   - Shows details for only one selected page at a time
+   - No multi-selection support
+
+4. **Same-Page Requirement**:
+   - Table and detail widgets must be on the same page
+   - Cannot connect to tables on other pages
+
+## Summary
+
+The Table Detail View Widget is a specialized component for implementing **master-detail UI patterns** in cplace. It provides a **dynamic, responsive detail panel** that synchronizes with table selections, offering:
+
+- **Space-efficient design**: Show summaries in tables, details in the panel
+- **Seamless interaction**: No page navigation required
+- **Flexible configuration**: Choose which attributes to display
+- **Event-driven updates**: Automatic synchronization with table selections
+- **Structured layout**: 3-column attribute display with optional header
+
+Choose this widget when you need to provide **additional context or detailed information** for items in a table without cluttering the table view or requiring users to navigate away from the overview.
+
+### Ideal Scenario
+
+**Best use**: A page with a table showing 20+ items where users need to quickly browse through items and view detailed information for each without opening separate pages. The table shows key identifying columns (name, status, date), while the detail panel shows comprehensive information (descriptions, metadata, relationships).