@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-platform-singleAttribute/research.md

@@ -0,0 +1,1094 @@
+# Widget Research: cf.platform.singleAttribute
+
+**Date**: 2026-01-16
+**Widget ID**: `cf.platform.singleAttribute`
+**Repository**: main
+**Definition Class**: `cf.cplace.platform.frontend.widgets.SingleAttributeWidgetDefinition`
+
+---
+
+## Executive Summary
+
+### Widget Description
+
+The Single Attribute Widget displays a single attribute (either custom or built-in) from a page with fine-grained control over label, value, and editing behavior. It provides flexible attribute presentation with optional in-place editing, alternative labels, and conditional visibility.
+
+### Primary Purpose
+
+This widget enables precise control over individual attribute display by allowing users to choose exactly which attribute to show, customize its presentation (label, value, or both), enable in-place editing, and conditionally show/hide the attribute based on business logic. Unlike the full Attributes widget, this focuses on a single attribute with maximum configuration flexibility.
+
+---
+
+## Core Functionality
+
+### What This Widget Does
+
+1. **Single Attribute Display**: Shows one specific attribute from a page (custom or built-in)
+2. **Flexible Presentation**: Configurable to display label only, value only, or both
+3. **In-Place Editing**: Optional inline editing without form submission
+4. **Custom Labels**: Support for alternative/localized labels instead of default attribute names
+5. **Layout Control**: Single or two-column display modes
+6. **Conditional Visibility**: cplaceJS script support to show/hide attributes dynamically
+7. **Parent Navigation**: Can display attributes from the parent page in hierarchical structures
+
+### Key Characteristics
+
+- **Attribute Selection**: Dynamic enumeration of available attributes (both custom and built-in) based on target entity type
+- **Configuration Flexibility**: 11 configuration parameters providing extensive customization
+- **Embedding Context**: Can be embedded directly on pages or within Attributes Group widgets
+- **Frontend Duality**: Supports both legacy template rendering and new Angular component architecture
+- **Migration Support**: Handles legacy configurations with unquoted attribute names
+
+---
+
+## Use Cases
+
+### Primary Use Cases
+
+#### 1. Custom Attribute Layout
+
+**Scenario**: Display specific attributes in a custom page layout without showing all attributes
+
+**Example**: Create a summary section at the top of a page showing only critical attributes (status, priority, owner) while keeping detailed attributes in a separate section.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.status` (or built-in like `name`)
+- `WITH_LABEL`: `true`
+- `WITH_VALUE`: `true`
+- `IN_PLACE_EDITING`: `false`
+
+**When to use**:
+- Need precise control over which attributes appear where
+- Building custom dashboards or summary views
+- Creating multi-section page layouts
+
+---
+
+#### 2. Read-Only Attribute Display with Alternative Labels
+
+**Scenario**: Show attribute values with custom, user-friendly labels
+
+**Example**: Display a technical attribute like `cf.cplace.solution.internalCode` with a friendlier label "Product Code" for business users.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.internalCode`
+- `LOCALIZED_ALTERNATIVE_LABEL`: {"en": "Product Code", "de": "Produktcode"}
+- `WITH_LABEL`: `true`
+- `WITH_VALUE`: `true`
+- `IN_PLACE_EDITING`: `false`
+
+**Benefits**:
+- Improve UX with domain-specific terminology
+- Support multiple languages with localized labels
+- Hide technical attribute names from end users
+
+---
+
+#### 3. Quick Edit Interface
+
+**Scenario**: Enable rapid editing of specific attributes without opening full edit forms
+
+**Example**: Allow users to quickly update task status or priority directly from a page view.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.status`
+- `WITH_LABEL`: `true`
+- `WITH_VALUE`: `true`
+- `IN_PLACE_EDITING`: `true`
+- `RELOAD_AFTER_CHANGE`: `true` (if other widgets depend on this attribute)
+
+**Benefits**:
+- Reduce clicks and page transitions
+- Improve user productivity for frequent updates
+- Maintain context while editing
+
+**Note**: The widget wraps the attribute in a `<span class="cplace-single-attribute">` with JavaScript handling for in-place editing.
+
+---
+
+#### 4. Conditional Attribute Display
+
+**Scenario**: Show/hide attributes based on dynamic conditions
+
+**Example**: Display "Rejection Reason" only when a request's status is "Rejected", or show "Approval Date" only for approved items.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.rejectionReason`
+- `SHOW_ATTRIBUTE_SCRIPT`: cplaceJS script
+- Script bindings: `targetEntity`, `embeddingPage`
+
+```javascript
+// Example: Only show rejection reason if status is 'Rejected'
+return targetEntity.get('cf.cplace.solution.status') === 'Rejected';
+```
+
+**Benefits**:
+- Reduce visual clutter by hiding irrelevant fields
+- Implement state-dependent UIs
+- Create dynamic forms that adapt to data
+
+---
+
+#### 5. Parent Page Attribute Display
+
+**Scenario**: Display attributes from a parent page in a hierarchical structure
+
+**Example**: Show project-level attributes on task pages without duplicating data.
+
+**Configuration**:
+- `TARGET_ENTITY`: (leave empty)
+- `USE_PARENT`: `true`
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.projectBudget`
+
+**Use case**:
+- Hierarchical page structures (projects → tasks → subtasks)
+- Avoid data duplication
+- Show contextual information from parent entities
+
+---
+
+#### 6. Label-Only Display
+
+**Scenario**: Show just the attribute label without its value
+
+**Example**: Create headers or section labels using attribute names.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.description`
+- `WITH_LABEL`: `true`
+- `WITH_VALUE`: `false`
+
+**Note**: According to code validation (line 371-372), you cannot set both `WITH_LABEL` and `WITH_VALUE` to false - at least one must be enabled.
+
+---
+
+#### 7. Value-Only Display (Clean Display)
+
+**Scenario**: Show attribute values without labels in compact layouts
+
+**Example**: Display status badges, icons, or values in dense UIs where labels would be redundant.
+
+**Configuration**:
+- `ATTRIBUTE_NAME`: `cf.cplace.solution.status`
+- `WITH_LABEL`: `false`
+- `WITH_VALUE`: `true`
+- `IN_PLACE_EDITING`: `false`
+
+**Behavior**: When embedded in a regular page (not DummyWidgetContainer), uses `getCleanValueRepresentation()` which renders:
+- **References**: As clickable links
+- **Enumerations**: With icons and colors
+- **Attributes**: As plain values
+
+---
+
+#### 8. Embedded in Attributes Group Widget
+
+**Scenario**: Build custom forms by embedding multiple single attribute widgets in an Attributes Group layout
+
+**Example**: Create a two-column form where left column shows general info and right column shows technical details.
+
+**Configuration**:
+- Embedded within `cf.cplace.platform.attributesGroup` widget
+- `SINGLE_COLUMN` setting inherited from parent widget
+- Multiple single attribute widgets arranged in rows and columns
+
+**Benefits**:
+- Maximum layout flexibility
+- Mix different widget types (single attributes + other widgets)
+- Responsive to parent widget settings
+
+---
+
+### When to Use This Widget
+
+Choose `cf.platform.singleAttribute` when you need:
+
+- **Specific Attribute Display**: Show one particular attribute, not all attributes
+- **Custom Labels**: Alternative or localized labels instead of default names
+- **In-Place Editing**: Quick editing without form submission
+- **Conditional Visibility**: Show/hide based on business logic
+- **Layout Precision**: Exact placement of individual attributes in custom layouts
+- **Value-Only Display**: Clean rendering without labels
+- **Parent Navigation**: Display attributes from parent pages
+
+---
+
+### When NOT to Use This Widget
+
+Use alternatives when:
+
+- **All Attributes Needed**: Use `cf.platform.attributes` (Attributes widget) for complete display
+- **Multiple Attributes with Custom Layout**: Use `cf.cplace.platform.attributesGroup` (Attributes Group widget) for complex layouts
+- **Table-Connected Display**: Use `cf.platform.connectedSingleAttribute` for displaying attributes from selected table rows
+- **Simple Default Display**: Standard Attributes widget may be simpler for basic needs
+
+---
+
+## Configuration Concepts
+
+### Configuration Parameters Overview
+
+The widget provides 11 configuration parameters grouped into several categories:
+
+#### 1. Target Entity Selection
+
+**1.1 TARGET_ENTITY** (Page Reference, optional)
+- **Default**: Current embedding page
+- **Purpose**: Specify which page's attribute to display
+- **Type**: `SinglePageReferenceAttributeDef`
+- **Constraint**: Links to any page type
+- **Help**: "The page of which an attribute is shown. Leave empty for current page."
+
+**1.2 USE_PARENT** (Boolean, default: false)
+- **Purpose**: Display attribute from the parent page instead of the target entity
+- **Use case**: Hierarchical structures where child pages need parent information
+- **Behavior**: If enabled and target entity has a parent, uses parent entity
+
+**Note**: When embedded in a DummyWidgetContainer (within Attributes Group), these parameters are hidden and inherited from the parent configuration.
+
+---
+
+#### 2. Attribute Selection
+
+**2.1 ATTRIBUTE_NAME** (String Enumeration, required)
+- **Internal Name**: `cf.platform.quotedAttributeName`
+- **Purpose**: Select which attribute to display
+- **Type**: `SingleStringAttributeDef` with `DynamicStringEnumerationConstraint`
+- **Provider**: `AttributeNameEnumerationProvider`
+- **Options**: Dynamic list of available attributes from target entity type
+  - **Custom Attributes**: Names like `cf.cplace.solution.status` (quoted)
+  - **Built-in Attributes**: Feature names like `name`, `creator`, `created`
+- **Sorting**: Alphabetically by localized display name
+- **Migration**: Handles legacy unquoted names (deprecated `UNQUOTED_ATTRIBUTE_NAME`)
+
+**Implementation Details**:
+- The enumeration provider analyzes the target entity's type definition
+- Lists all custom attributes from `getAttributeDefinitions()`
+- Lists all built-in features from `getFeaturesInSearchIndexExceptDummyAttributes()`
+- Options show localized names but store technical attribute names
+
+---
+
+#### 3. Display Options
+
+**3.1 WITH_LABEL** (Boolean, default: false)
+- **Purpose**: Show the attribute name/label
+- **When true**: Displays the attribute label (or alternative label if configured)
+- **When false**: Hides the label, shows only value
+
+**3.2 WITH_VALUE** (Boolean, default: true)
+- **Purpose**: Show the attribute value
+- **When true**: Displays the attribute's current value
+- **When false**: Shows only the label
+- **Help**: "Determines if the attribute value should be shown. If not, the parameter 'Show attribute name' has to be set, and only the localized display name of the attribute will be shown."
+
+**Validation**: At least one of `WITH_LABEL` or `WITH_VALUE` must be `true` (validated in `isConfigurationComplete()` line 371-372).
+
+**3.3 LOCALIZED_ALTERNATIVE_LABEL** (Localized String, optional)
+- **Purpose**: Use a custom label instead of the attribute's default name
+- **Type**: `SingleLocalizedStringAttributeDef`
+- **Format**: Multi-language support (e.g., {"en": "Project Code", "de": "Projektcode"})
+- **Behavior**: If empty, uses attribute's default localized name
+- **Migration**: Replaces deprecated `ALTERNATIVE_LABEL` (plain string)
+
+---
+
+#### 4. Editing Behavior
+
+**4.1 IN_PLACE_EDITING** (Boolean, default: false)
+- **Purpose**: Enable inline editing without form submission
+- **When true**: Attribute becomes editable directly in the display
+- **Implementation**: Uses `ShowControlSubstitution` with `NO_IN_PLACE_EDITING` parameter
+- **Frontend**: Wrapped in `<span class="cplace-single-attribute">` with JavaScript handler
+
+**4.2 RELOAD_AFTER_CHANGE** (Boolean, default: false)
+- **Purpose**: Reload the parent grouped widget after attribute value changes
+- **Use case**: When other widgets depend on this attribute's value
+- **Behavior**: Triggers page/widget refresh after edit
+- **State**: Passed to frontend as `reloadAfterChange` in widget state
+
+---
+
+#### 5. Layout Control
+
+**5.1 SINGLE_COLUMN** (Boolean, default: false)
+- **Purpose**: Display attribute in single-column layout instead of two-column
+- **Relevance**: Only effective when `WITH_LABEL` is `true`
+- **Help**: "Only is relevant if the attribute name is also shown."
+- **Inheritance**: When embedded in Attributes Group widget, inherited from parent's `SINGLE_COLUMN` setting
+- **Implementation**: Passed to `ShowControlSubstitution` as `SHOW_IN_ONE_COLUMN` parameter
+
+---
+
+#### 6. Conditional Visibility
+
+**6.1 SHOW_ATTRIBUTE_SCRIPT** (cplaceJS Script, optional)
+- **Purpose**: Dynamically determine if attribute should be shown
+- **Type**: `SingleStringAttributeDef` with `ScriptConstraint`
+- **Bindings**:
+  - `targetEntity`: The entity whose attribute is displayed
+  - `embeddingPage`: The page where the widget is embedded
+- **Behavior**:
+  - If script is empty: Attribute always shown (if feature exists)
+  - If script evaluates to `false`: Attribute is hidden (returns empty string)
+  - If script evaluates to `true` or any truthy value: Attribute is shown
+- **Evaluation**: Performed by `ConnectedSingleAttributeHandler.evaluateShowAttributeScript()`
+- **Help**: "A cplaceJS script to determine if the attribute should be shown. If the provided script is not empty AND if it evaluates to false, the attribute will be hidden."
+
+**Example Scripts**:
+
+```javascript
+// Show only for specific status
+return targetEntity.get('cf.cplace.solution.status') === 'In Progress';
+
+// Show based on user permissions
+return embeddingPage.get('cf.cplace.solution.owner') === cplace.session().user();
+
+// Show if value is not empty
+return targetEntity.get('cf.cplace.solution.description') !== null;
+```
+
+---
+
+#### 7. Frontend Technology
+
+**7.1 USE_NEW_FRONTEND** (Boolean, copied from WidgetTypes.FRONTEND_CONFIGURATION_MIXIN)
+- **Purpose**: Toggle between legacy HTML template and new Angular component rendering
+- **When true**: Uses `<cf-wc-bridge>` Angular component
+- **When false**: Uses legacy `<span class="cplace-single-attribute">` with template rendering
+- **State**: Different state objects passed to frontend based on this flag
+  - New: `SingleAttributeWidgetComponentInputs` wrapping `SingleAttributeWidgetState`
+  - Old: Simple JSON with `reloadAfterChange`, `attributeParameterName`, `widgetId`
+
+---
+
+### Configuration Type Definition
+
+**TypeDef**: `CONFIGURATION.TYPE` (line 284-299)
+
+Includes all configuration attributes:
+```java
+public static final TypeDef TYPE = new TypeDef(
+    KIND,
+    TARGET_ENTITY,           // Page selection
+    USE_PARENT,              // Parent navigation
+    UNQUOTED_ATTRIBUTE_NAME, // Deprecated
+    ATTRIBUTE_NAME,          // Current attribute selection
+    WITH_VALUE,              // Display value
+    WITH_LABEL,              // Display label
+    ALTERNATIVE_LABEL,       // Deprecated
+    LOCALIZED_ALTERNATIVE_LABEL, // Alternative label
+    IN_PLACE_EDITING,        // Editing
+    SINGLE_COLUMN,           // Layout
+    RELOAD_AFTER_CHANGE,     // Refresh behavior
+    SHOW_ATTRIBUTE_SCRIPT,   // Conditional visibility
+    USE_NEW_FRONTEND         // Technology toggle
+);
+```
+
+---
+
+### Configuration Visibility Rules
+
+**Conditional Display** (`showPropertyInEdit()`, line 432-451):
+
+When embedded in `DummyWidgetContainer` (inside Attributes Group), the following properties are **hidden**:
+- `TARGET_ENTITY`: Inherited from parent widget
+- `USE_PARENT`: Inherited from parent widget
+- `SINGLE_COLUMN`: Inherited from parent widget
+- `USE_NEW_FRONTEND`: Inherited from parent widget
+
+Always hidden (deprecated):
+- `UNQUOTED_ATTRIBUTE_NAME`: Migrated to `ATTRIBUTE_NAME`
+- `ALTERNATIVE_LABEL`: Migrated to `LOCALIZED_ALTERNATIVE_LABEL`
+
+---
+
+### Configuration Validation
+
+**Completeness Check** (`isConfigurationComplete()`, line 360-392):
+
+A configuration is complete when:
+
+1. **Base validation**: `super.isConfigurationComplete()` passes
+2. **Attribute selected**: `ATTRIBUTE_NAME` is not empty
+3. **Display option**: At least one of `WITH_LABEL` or `WITH_VALUE` is `true`
+4. **Attribute exists**: The selected attribute exists in at least one target type definition
+   - For custom attributes: Checks `getAttributeDefinitionByName()`
+   - For built-in attributes: Checks `getFeatureOrNull()`
+
+If any check fails, configuration is incomplete and widget may show error message.
+
+---
+
+## Context and Related Widgets
+
+### Widget Family: Attribute Display Widgets
+
+The cplace platform provides several widgets for displaying attributes, each serving different use cases:
+
+| Widget | Purpose | Attributes Shown | Configuration Level | Primary Use Case |
+|--------|---------|------------------|---------------------|------------------|
+| **cf.platform.attributes** | Show all attributes | All (automatic) | None | Complete attribute overview, default forms |
+| **cf.platform.singleAttribute** | Show one attribute | One (selected) | High (11 params) | Precise single attribute control with custom labels |
+| **cf.cplace.platform.attributesGroup** | Show selected attributes | Multiple (manual layout) | Very High | Custom forms with complex layouts |
+| **cf.platform.connectedSingleAttribute** | Show attribute from table row | One (from selection) | High + Connection | Dynamic attribute display based on table selection |
+
+---
+
+### Comparison: cf.platform.singleAttribute vs. Related Widgets
+
+#### vs. cf.platform.attributes
+
+| Aspect | cf.platform.singleAttribute | cf.platform.attributes |
+|--------|----------------------------|------------------------|
+| **Attributes Shown** | One (manually selected) | All (automatic) |
+| **Configuration** | 11 parameters | None |
+| **Label Customization** | Yes (alternative labels) | No |
+| **Conditional Display** | Yes (cplaceJS script) | No |
+| **In-place Editing** | Direct inline editing | Form-based editing |
+| **Layout Control** | Single/double column | Fixed vertical list |
+| **Use Case** | Precise control over one attribute | Quick display of all data |
+
+#### vs. cf.cplace.platform.attributesGroup
+
+| Aspect | cf.platform.singleAttribute | cf.cplace.platform.attributesGroup |
+|--------|-----------------------------|-------------------------------------|
+| **Scope** | Single attribute | Multiple attributes + widgets |
+| **Layout** | Individual widget placement | Row/column grid system |
+| **Embedding** | Standalone or within group | Standalone, contains other widgets |
+| **Configuration** | Per-attribute settings | Layout + child widget configurations |
+| **Complexity** | Simple | Complex |
+| **Typical Usage** | Building block | Container/orchestrator |
+
+**Relationship**: `cf.platform.singleAttribute` is designed to be embedded within `cf.cplace.platform.attributesGroup` widgets. The group widget provides the layout structure, while single attribute widgets populate individual cells.
+
+**Implementation Note**: `canBeEmbeddedInsideWidgetOfType()` (line 792-794) returns `true` only for `AttributesGroupWidgetDefinition.class`.
+
+#### vs. cf.platform.connectedSingleAttribute
+
+| Aspect | cf.platform.singleAttribute | cf.platform.connectedSingleAttribute |
+|--------|----------------------------|-------------------------------------|
+| **Data Source** | Fixed page (embedding or selected) | Dynamic (from table selection) |
+| **Selection Mode** | Static configuration | Dynamic user selection |
+| **Update Behavior** | Static (page reload to change) | Real-time (selection changes) |
+| **Use Case** | Fixed attribute display | Master-detail interfaces |
+| **Configuration** | Similar parameters + target entity | Similar parameters + connection config |
+
+**Key Difference**: The "connected" variant implements `ISingleEntitySelectionProducer` interface and reacts to entity selections from connected table widgets.
+
+---
+
+### Embedding Rules and Restrictions
+
+#### Where This Widget Can Be Embedded
+
+**Allowed**:
+1. **CustomEntity pages**: Standard entity pages with type definitions
+2. **Rich string content**: Can be embedded in rich text fields
+3. **Widget containers**: Specifically within `AttributesGroupWidgetDefinition`
+
+**Validation**: `checkEmbeddableIn()` (line 336-338)
+```java
+checkIsEmbeddedInRichStringOrInWidget(entity, embedding);
+```
+
+This allows embedding:
+- Directly on pages
+- Inside rich text attributes
+- Within compatible widget containers (Attributes Group)
+
+#### Embedding Context Detection
+
+The widget determines its embedding context in `init()` (line 544-583):
+
+**Case 1: Embedded in DummyWidgetContainer** (inside Attributes Group)
+- `embeddingEntity`: The page where the Attributes Group widget is embedded
+- `singleColumn`: Inherited from parent widget's setting
+- Configuration: Some parameters hidden in edit mode
+
+**Case 2: Direct Embedding** (on page or rich string)
+- `embeddingEntity`: The page itself
+- `singleColumn`: Uses widget's own setting
+- Configuration: All parameters visible in edit mode
+
+---
+
+### Template and Rendering
+
+#### Template File
+
+**Location**: `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/singleAttributeWidgetDefinition.htm`
+
+**Content** (line 1):
+```html
+$[useNewFrontend$<cf-wc-bridge ng-cloak route="cplace-single-attribute-widget" name="cf-platform" remoteurl="$cfPlatformAppRemoteUrl()$" data="$singleAttributeWidgetState$"></cf-wc-bridge>$]useNewFrontend[$<span class="cplace-single-attribute" cplace-single-attribute="$state$" data-qa-element-name="$internalName$">$value$</span>$useNewFrontend]$
+```
+
+**Structure**:
+- **Conditional rendering** based on `useNewFrontend` flag
+- **New Frontend**: Angular component via `<cf-wc-bridge>`
+  - Route: `cplace-single-attribute-widget`
+  - State: `singleAttributeWidgetState` (JSON)
+- **Legacy Frontend**: HTML span with JavaScript directive
+  - Class: `cplace-single-attribute`
+  - Directive: `cplace-single-attribute="$state$"`
+  - Content: `$value$` (rendered attribute)
+  - QA Element: `data-qa-element-name="$internalName$"` for testing
+
+#### Template Substitutions
+
+**WidgetTemplateSubstitution** (`widgetSubstitution()`, line 523-719):
+
+**Substitution Variables**:
+
+1. **useNewFrontend** (Conditional)
+   - Type: `ConditionalSubstitution`
+   - Purpose: Controls template branching
+
+2. **singleAttributeWidgetState** (New Frontend Only)
+   - Type: JSON string (HTML attribute escaped)
+   - Content: `SingleAttributeWidgetComponentInputs` wrapping `SingleAttributeWidgetState`
+   - Generated by: `getWidgetState()` method
+
+3. **state** (Legacy Frontend Only)
+   - Type: JSON string (HTML attribute escaped)
+   - Content: `{ reloadAfterChange, attributeParameterName, widgetId }`
+
+4. **value** (Legacy Frontend Only)
+   - Type: HTML content (no escaping)
+   - Generated by: `showAttribute()` method
+   - Uses: `threadLocalNestedPrintingContext` to prevent infinite recursion
+
+5. **internalName** (Legacy Frontend Only)
+   - Type: Attribute name (HTML attribute escaped)
+   - Purpose: Test automation and debugging
+
+#### Attribute Rendering Methods
+
+**showAttribute()** (line 621-694):
+
+**Rendering Logic**:
+
+1. **Validation**:
+   - Check if `targetEntity` exists → Returns `entityNotFound` message
+   - Check if `feature` exists → Returns empty string
+   - Check if hidden by extension → Returns empty string
+   - Evaluate `SHOW_ATTRIBUTE_SCRIPT` → Returns empty string if should hide
+
+2. **Read Configuration**:
+   - `withValue`, `withLabel`, `inPlaceEditing` from widget config
+   - `localizedAlternativeLabel` from widget config (or empty)
+
+3. **Cycle Prevention**:
+   - Track `targetEntity.uid + '/' + attributeName` in thread-local set
+   - Prevent infinite recursion if attribute references create cycles
+   - Return `configurationError` message if cycle detected
+
+4. **Type Validation**:
+   - For custom attributes: Verify attribute exists in type definition
+   - Return `null` if attribute not found
+
+5. **Rendering Strategy** (three paths):
+
+   **Path A: Clean Value Representation** (no label, no editing, not in dummy)
+   - Uses: `getCleanValueRepresentation(feature)`
+   - Renders: Plain values, links for references, enumerations with icons
+
+   **Path B: Label Only** (no value, no editing)
+   - Uses: Alternative label or `feature.getLabelOrName().get()`
+   - Renders: Plain text label
+
+   **Path C: Standard Show Control** (default)
+   - Uses: `FunctionsHelper.proxy("show", feature, ...)`
+   - Parameters:
+     - `NO_VALUE`: Inverted `withValue`
+     - `NO_LABEL`: Inverted `withLabel`
+     - `NO_IN_PLACE_EDITING`: Inverted `inPlaceEditing`
+     - `ALTERNATIVE_LABEL`: Custom label text
+     - `SHOW_IN_ONE_COLUMN`: `singleColumn` setting
+     - `PARAMETER_HIDE_OVERRIDDEN`: Flag
+   - Renders: Full show control with label, value, and optional editing
+
+**getCleanValueRepresentation()** (line 721-751):
+
+Handles different feature types:
+
+- **CustomAttribute**: Uses `ValuesWithConstraintSubstitutions` template
+- **TypeLayoutAttribute / CustomTypeAttribute**: Renders as link
+- **Regular Attribute**: Renders as plain value
+- **OneReference**: Renders as link (handles `InheritRightsOnePersonReference`)
+- **ManyReference**: Renders as comma-separated links (handles `InheritRightsManyReference`)
+
+---
+
+### Widget Title Generation
+
+**getTitle()** (line 697-717):
+
+**Logic**:
+1. Collect all possible attribute display names from target type definitions
+2. For custom attributes: Use `getLocalizedName()` from `AttributeDefinition`
+3. For built-in attributes: Use `getLabelOrName().get()` from `Feature`
+4. Sort alphabetically and join with `, ` separator
+5. Return as dynamic message
+
+**Use case**: Displayed in widget chrome/frame or layout editors.
+
+**Example**: If attribute exists in multiple type definitions with different names, shows all: "Status, State"
+
+---
+
+## Implementation Details
+
+### Widget Definition Properties
+
+| Property | Value |
+|----------|-------|
+| **Widget Kind** | `cf.platform.singleAttribute` |
+| **Definition Class** | `SingleAttributeWidgetDefinition` |
+| **Package** | `cf.cplace.platform.frontend.widgets` |
+| **Icon** | `fa-pen-square` |
+| **App** | `PlatformPlugin.INSTANCE().platformApp` |
+| **Configuration Type** | `CONFIGURATION.TYPE` (11 attributes) |
+| **Template** | `singleAttributeWidgetDefinition.htm` |
+| **Widget Name (EN)** | "Single Attribute of a page" |
+| **Widget Name (DE)** | "Einzelnes Attribut einer Seite" |
+
+---
+
+### Migration and Backward Compatibility
+
+#### Attribute Name Migration
+
+**Original Implementation** (pre-4.36):
+- Only custom attributes supported
+- Names stored unquoted in `UNQUOTED_ATTRIBUTE_NAME`
+- Format: Simple name (e.g., `status`)
+
+**Current Implementation** (since 4.36):
+- Both custom and built-in attributes supported
+- Names stored quoted in `ATTRIBUTE_NAME`
+- Format: Fully qualified name (e.g., `cf.cplace.solution.status` or `name`)
+
+**Migration Process** (`migrateWidgetConfiguration()`, line 398-429):
+
+1. Check if `ATTRIBUTE_NAME` is empty
+2. If empty, read `UNQUOTED_ATTRIBUTE_NAME`
+3. If unquoted name exists:
+   - If already quoted: Use as-is
+   - If unquoted: Convert using `CustomAttribute.getNameFromSimpleName()`
+4. Set `ATTRIBUTE_NAME` with converted value
+5. Clear `UNQUOTED_ATTRIBUTE_NAME`
+6. Log migration event
+
+**Backward Compatibility**: `getAttributeName()` helper (line 347-357) checks both attributes, preferring the new one.
+
+#### Alternative Label Migration
+
+**Original**: `ALTERNATIVE_LABEL` (plain string)
+**Current**: `LOCALIZED_ALTERNATIVE_LABEL` (LocalizedString)
+
+**Migration**: Handled by `migrateUnlocalizedStringToLocalizedString()` (line 423-428)
+
+---
+
+### Permission and Security
+
+#### Entity-Level Permissions
+
+**Read Permission**: Required to view the widget and attribute value
+
+**Edit Permission**: Required for in-place editing (when `IN_PLACE_EDITING` is enabled)
+
+**Attribute-Level Permissions**: Attributes may have additional read/write restrictions based on type definition
+
+#### Attribute Hiding Extensions
+
+**Pro-Code Extension Point**: `HideAttributeInGroupedAttributesWidget`
+
+**Purpose**: Allow custom code to hide attributes based on business logic
+
+**Evaluation Points**:
+1. In `showAttribute()` (line 626): During template rendering
+2. In `shouldShowAttributeValue()` (line 882-885): During state generation
+
+**Implementation**:
+```java
+if (HideAttributeInGroupedAttributesWidget.shouldHide(feature, embeddingEntity)) {
+    return "";
+}
+```
+
+---
+
+### State Management
+
+#### Widget State Object
+
+**Class**: `SingleAttributeWidgetState` (DTO)
+
+**Generated by**: `getWidgetState()` (line 803-864)
+
+**State Properties**:
+- `targetEntityUid`: UID of entity whose attribute is shown
+- `embeddingEntityUid`: UID of page where widget is embedded
+- `widgetId`: Unique widget identifier
+- `attributeName`: Fully qualified attribute name
+- `withValue`: Display value flag
+- `withLabel`: Display label flag
+- `alternativeLabel`: Custom label text (or null)
+- `noInPlaceEditing`: Inverted `IN_PLACE_EDITING` flag
+- `reload`: `RELOAD_AFTER_CHANGE` flag
+- `singleColumn`: Layout mode
+- `parentWidgetId`: ID of parent Attributes Group widget (or null)
+- `invalidConfigurationMessage`: Error message if incomplete (or null)
+- `showAttribute`: Result of visibility evaluation
+- `attributeValue`: Reserved (currently null)
+
+**Usage**:
+- **New Frontend**: Wrapped in `SingleAttributeWidgetComponentInputs` and serialized to JSON
+- **Legacy Frontend**: Partial state (only `reloadAfterChange`, `attributeParameterName`, `widgetId`) serialized to JSON
+
+---
+
+### Thread-Local Context
+
+**Purpose**: Prevent infinite recursion when attributes reference each other
+
+**Implementation**: `threadLocalNestedPrintingContext` (line 514-521)
+
+**Context Class**: `NestedPrintingContext` with `Set<String> idsForCyclePrevention`
+
+**Usage** (in `showAttribute()`):
+1. Build ID: `targetEntity.uid + '/' + attributeName`
+2. Check if ID already in set → Return error
+3. Add ID to set
+4. Render attribute
+5. Remove ID from set
+
+**Example Cycle**:
+- Task A displays project attribute
+- Project widget displays "recent task" attribute
+- Recent task is Task A
+- Without cycle prevention: Infinite loop
+- With cycle prevention: Returns `configurationError` message
+
+---
+
+### Dynamic Attribute Enumeration
+
+#### AttributeNameEnumerationProvider
+
+**Class**: `AttributeNameEnumerationProvider` (line 109-164)
+
+**Extends**: `DynamicEnumerationProvider.DynamicStringEnumerationProvider`
+
+**Purpose**: Populate attribute dropdown in widget configuration based on target entity type
+
+**Method**: `getStringEnumOptions()` (line 113-127)
+
+**Process**:
+1. Verify owner entity is a `WidgetConfiguration`
+2. Get target type definitions using `getTargetTypeDefinitions()`
+3. Collect custom attribute options
+4. Collect built-in attribute options
+5. Sort and return combined list
+
+**Custom Attributes** (`getCustomStringEnumOptions()`, line 129-144):
+- Iterate through type definition's attribute definitions
+- Extract simple name from `_name().get()`
+- Convert to fully qualified name using `CustomAttribute.getNameFromSimpleName()`
+- Create option with name and localized display name
+- Use `Set` to deduplicate across multiple type definitions
+
+**Built-in Attributes** (`getBuiltinStringEnumOptions()`, line 146-157):
+- Get prototype entity from type definition
+- Iterate through `getFeaturesInSearchIndexExceptDummyAttributes()`
+- Create option with feature name and localized label
+- Use `Set` to deduplicate
+
+**Sorting**: `sortOptions()` (line 159-163) sorts by display name using `DynamicEnumerationOption.SORT_BY_NAME`
+
+---
+
+## Code References
+
+### Core Files
+
+| Component | Path | Line Range |
+|-----------|------|------------|
+| **Widget Definition** | `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/SingleAttributeWidgetDefinition.java` | 83-900 |
+| **Template** | `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/singleAttributeWidgetDefinition.htm` | 1-2 |
+| **English Messages** | `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_en.properties` | 4306-4323 |
+| **German Messages** | `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_de.properties` | 4306-4323 |
+
+### Key Classes and Methods
+
+**Configuration**:
+- `CONFIGURATION.TYPE`: Line 284-299
+- `getConfigurationType()`: Line 324-327
+- `showPropertyInEdit()`: Line 432-451
+- `isConfigurationComplete()`: Line 360-392
+- `migrateWidgetConfiguration()`: Line 398-429
+
+**Rendering**:
+- `getContentSubstitution()`: Line 330-333
+- `widgetSubstitution()`: Line 527-719
+- `putSubstitutions()`: Line 586-619
+- `showAttribute()`: Line 621-694
+- `getCleanValueRepresentation()`: Line 721-751
+
+**Utility**:
+- `getAttributeName()`: Line 347-357
+- `getTarget()`: Line 454-469
+- `getTargetTypeDefinitions()`: Line 480-507
+- `AttributeNameEnumerationProvider`: Line 109-164
+
+**State Management**:
+- `getWidgetState()`: Line 803-864
+- `shouldShowAttributeValue()`: Line 873-899
+
+---
+
+## Internationalization
+
+### English Translations
+
+**Widget**:
+- `name`: "Single Attribute of a page"
+
+**Configuration Labels**:
+- `entity_name`: "Page"
+- `entity_shortHelp`: "The page of which an attribute is shown. Leave empty for current page."
+- `attributeName_name`: "Attribute name"
+- `withLabel_name`: "Show attribute name"
+- `withValue_name`: "Show attribute value"
+- `withValue_shortHelp`: "Determines if the attribute value should be shown. If not, the parameter 'Show attribute name' has to be set, and only the localized display name of the attribute will be shown."
+- `inPlaceEditing_name`: "Allow in-place editing"
+- `singleColumn_name`: "Show attribute in single column"
+- `singleColumn_shortHelp`: "Only is relevant if the attribute name is also shown."
+- `alternativeLabel_name`: "Alternative Attribute Label"
+- `useParent_name`: "Use parent page"
+- `reloadAfterChange_name`: "Reload grouped widget after attribute change"
+- `showAttributeScript_name`: "Show attribute"
+- `showAttributeScript_shortHelp`: "A cplaceJS script to determine if the attribute should be shown. If the provided script is not empty AND if it evaluates to false, the attribute will be hidden. Use 'targetEntity' to access the target entity and use 'embeddingPage' to access the current embedding entity."
+
+**Messages**:
+- `entityNotFound`: "No page selected"
+- `configurationError`: "Configuration error"
+- `configuration_error`: "Configuration error"
+
+### German Translations
+
+**Widget**:
+- `name`: "Einzelnes Attribut einer Seite"
+
+**Configuration Labels**:
+- `entity_name`: "Seite"
+- `entity_shortHelp`: "Die Seite, deren Attribut angezeigt werden soll. Lassen Sie den Wert leer, um die aktuelle Seite zu verwenden."
+- `attributeName_name`: "Attributname"
+- `withLabel_name`: "Auch den Attributnamen anzeigen"
+- `withValue_name`: "Attributwert anzeigen"
+- `withValue_shortHelp`: "Bestimmt, ob der Wert des Attributs angezeigt werden soll. Wenn nein, muss die Option 'Auch den Attributnamen anzeigen' gesetzt sein, und es wird nur der Anzeigename des Attributs ausgegeben."
+- `inPlaceEditing_name`: "Bearbeitung zulassen"
+- `singleColumn_name`: "Attribut einspaltig anzeigen"
+- `singleColumn_shortHelp`: "Attribut einspaltig anzeigen hat nur Auswirkungen wenn Attributname angezeigt wird."
+- `alternativeLabel_name`: "Alternatives Attributlabel"
+- `useParent_name`: "Übergeordnete Seite verwenden"
+- `reloadAfterChange_name`: "Gruppierungswidget bei Wertänderung des Attributs neu laden"
+- `showAttributeScript_name`: "Attribut anzeigen"
+- `showAttributeScript_shortHelp`: "Ein cplaceJS Skript um zu bestimmen ob das Attribut angezeigt werden soll oder nicht. Wenn das angegebene Skript nicht leer ist UND wenn dessen Ergebnis false liefert, wird das Attribut versteckt. Über 'targetEntity' kann auf die aktuell ausgewählte Entität zugegriffen werden, und 'embeddingPage' kann verwendet werden, um auf die aktuelle Einbettungseinheit Entität."
+
+---
+
+## Architecture and Design Patterns
+
+### Design Philosophy
+
+The `cf.platform.singleAttribute` widget embodies the "flexible building block" principle:
+
+- **Composability**: Designed to be embedded within larger layouts (Attributes Group widgets)
+- **Configurability**: Extensive parameters for precise control
+- **Reusability**: Same widget serves multiple use cases through configuration
+- **Separation of Concerns**: Rendering logic separated into template, state, and helper methods
+
+### Template Pattern Usage
+
+The widget uses cplace's template system with substitution pattern:
+
+```
+WidgetTemplateSubstitution
+  → putSubstitutions()
+    → Conditional: useNewFrontend
+    → PrintSubstitution: state / singleAttributeWidgetState
+    → PrintSubstitution: value (calls showAttribute())
+    → PrintSubstitution: internalName
+```
+
+**showAttribute() Call Chain**:
+```
+showAttribute()
+  → FunctionsHelper.proxy("show", feature, parameters)
+    → ShowControlSubstitution
+      → Template rendering of attribute control
+```
+
+### State Object Pattern
+
+The widget implements a clear separation between configuration and runtime state:
+
+**Configuration** (persisted):
+- Stored in `WidgetConfiguration` entity
+- 11 configuration attributes
+- Editable by users with permissions
+
+**Runtime State** (computed):
+- Generated by `getWidgetState()` at render time
+- Combines configuration, entity data, and evaluation results
+- Passed to frontend as JSON
+
+**Benefits**:
+- Clean architecture
+- Frontend can be stateless
+- Easy to debug and test
+
+### Cycle Prevention Pattern
+
+Uses thread-local storage to prevent infinite recursion:
+
+```java
+ThreadLocalNestingContext<NestedPrintingContext>
+  → createContext() → new NestedPrintingContext()
+    → idsForCyclePrevention: Set<String>
+```
+
+**Pattern**:
+1. Store currently rendering entity+attribute combinations in thread-local set
+2. Check before rendering each attribute
+3. Clean up after rendering
+
+**Use case**: Prevents infinite loops when attributes reference each other in complex object graphs.
+
+### Dynamic Enumeration Pattern
+
+**Challenge**: Attribute dropdown options depend on target entity type, which varies per widget instance
+
+**Solution**: `DynamicEnumerationProvider` pattern
+- Provider class registered in configuration
+- Invoked at runtime when widget is configured
+- Analyzes current context (widget configuration, embedding entity)
+- Returns type-specific options
+
+**Benefits**:
+- Type-safe attribute selection
+- Prevents configuration errors
+- Better UX with searchable dropdowns
+
+---
+
+## Related Research Documents
+
+- **AttributesWidgetDefinition**: `/Users/thomasbuechner/dev/repos/cplace-ga-products/specs/2026-01-16/cf-platform-attributes/research.md`
+- **AttributesGroupWidgetDefinition**: `/Users/thomasbuechner/dev/repos/cplace-ga-products/specs/2026-01-16/cf-cplace-platform-attributesGroup/research.md`
+- **ConnectedSingleAttributeWidgetDefinition**: `/Users/thomasbuechner/dev/repos/cplace-ga-products/specs/2026-01-16/cf-platform-connectedSingleAttribute/research.md`
+
+---
+
+## Key Takeaways
+
+1. **Maximum Flexibility**: 11 configuration parameters provide fine-grained control over single attribute display
+2. **Composable Design**: Intended to be embedded in Attributes Group widgets for complex layouts
+3. **Conditional Logic**: cplaceJS script support enables dynamic, business-rule-driven UIs
+4. **Migration Ready**: Handles legacy configurations and supports gradual frontend migration
+5. **Type-Safe Configuration**: Dynamic enumeration ensures only valid attributes can be selected
+6. **Edit Optimization**: In-place editing reduces user friction for frequent updates
+7. **Multi-Language Support**: Localized alternative labels for international deployments
+8. **Parent Navigation**: Hierarchical page structures supported via `USE_PARENT` flag
+9. **Cycle Prevention**: Thread-local tracking prevents infinite recursion in complex object graphs
+10. **Dual Frontend**: Supports both legacy and modern Angular architecture
+
+---
+
+## Recommendations for Documentation
+
+### Short Description
+
+"Displays a single attribute from a page with flexible label, value, and editing options, including in-place editing and conditional visibility."
+
+### Use Case Summary
+
+**Best suited for**:
+- Custom page layouts requiring precise attribute placement
+- In-place editing of specific attributes without form submission
+- Conditional attribute display based on business logic
+- Alternative or localized attribute labels
+- Building blocks within Attributes Group layouts
+- Parent page attribute display in hierarchical structures
+
+**Consider alternatives when**:
+- All attributes need to be displayed → Use `cf.platform.attributes`
+- Complex multi-attribute layouts needed → Use `cf.cplace.platform.attributesGroup` (as container)
+- Table-connected dynamic display needed → Use `cf.platform.connectedSingleAttribute`
+
+### Configuration Guidance
+
+**Essential Settings**:
+1. **ATTRIBUTE_NAME** (required): Select which attribute to display
+2. **WITH_LABEL** / **WITH_VALUE**: At least one must be enabled
+
+**Common Configurations**:
+
+**Standard Display**: Show label and value
+- `WITH_LABEL`: true
+- `WITH_VALUE`: true
+- `IN_PLACE_EDITING`: false
+
+**Quick Edit**: Enable inline editing
+- `WITH_LABEL`: true
+- `WITH_VALUE`: true
+- `IN_PLACE_EDITING`: true
+- `RELOAD_AFTER_CHANGE`: true (if other widgets depend on this)
+
+**Custom Label**: Use alternative label
+- `LOCALIZED_ALTERNATIVE_LABEL`: {"en": "Custom Name", "de": "Benutzerdefinierter Name"}
+- `WITH_LABEL`: true
+- `WITH_VALUE`: true
+
+**Conditional Display**: Show/hide based on logic
+- `SHOW_ATTRIBUTE_SCRIPT`: cplaceJS code
+- Example: `return targetEntity.get('status') === 'Active';`
+
+**Parent Navigation**: Display parent attribute
+- `USE_PARENT`: true
+- `ATTRIBUTE_NAME`: Attribute from parent entity
+
+**Layout Options**:
+- `SINGLE_COLUMN`: true (full-width display when label is shown)
+- `SINGLE_COLUMN`: false (default two-column layout)
+
+---
+
+## Appendix: Configuration Matrix
+
+### All Configuration Parameters
+
+| # | Parameter | Type | Default | Required | Description |
+|---|-----------|------|---------|----------|-------------|
+| 1 | `TARGET_ENTITY` | Page Reference | Current page | No | Page whose attribute is displayed |
+| 2 | `USE_PARENT` | Boolean | false | No | Use parent page instead of target |
+| 3 | `ATTRIBUTE_NAME` | String Enum | - | Yes | Attribute to display |
+| 4 | `WITH_LABEL` | Boolean | false | No* | Show attribute label |
+| 5 | `WITH_VALUE` | Boolean | true | No* | Show attribute value |
+| 6 | `LOCALIZED_ALTERNATIVE_LABEL` | Localized String | - | No | Custom label |
+| 7 | `IN_PLACE_EDITING` | Boolean | false | No | Enable inline editing |
+| 8 | `SINGLE_COLUMN` | Boolean | false | No | Full-width layout |
+| 9 | `RELOAD_AFTER_CHANGE` | Boolean | false | No | Reload parent widget after edit |
+| 10 | `SHOW_ATTRIBUTE_SCRIPT` | cplaceJS | - | No | Conditional visibility script |
+| 11 | `USE_NEW_FRONTEND` | Boolean | - | No | Use Angular component |
+
+\* At least one of `WITH_LABEL` or `WITH_VALUE` must be true
+
+---
+
+**End of Research Document**