@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,426 @@
+# Widget Research: cf.cplace.documentation.navigationWidget
+
+**Research Date:** 2026-01-16
+**Widget ID:** `cf.cplace.documentation.navigationWidget`
+**Widget Name:** Title and Page Links
+**Repository:** cplace-paw
+**Plugin:** cf.cplace.documentation
+
+---
+
+## 1. Widget Purpose
+
+### Core Functionality
+
+The **Documentation Navigation Widget** is a visual navigation component designed to create clear entry points and navigation aids within cplace workspaces. It displays a prominent title (with optional page link) and a collection of page links in a visually appealing, color-coded tile format with an icon.
+
+### Short Description
+
+This widget creates a styled navigation tile that combines a title, multiple page links, and an icon to provide intuitive navigation entry points for documentation and content structures.
+
+### Technical Implementation
+
+- **Definition Class:** `cf.cplace.documentation/src/main/java/cf/cplace/documentation/script/DocumentationWidgetDefinition.java`
+- **Icon:** `fa-sitemap` (representing a hierarchical navigation structure)
+- **Frame Display:** No frame (`showFrame() = false`)
+- **Padding:** No padding (`isNoPadding() = true`)
+- **Template:** `documentationWidgetDefinition.htm`
+
+---
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Documentation Portal Entry Pages**
+   - Create visually appealing landing pages for documentation areas
+   - Provide clear entry points to different documentation sections
+   - Example: A "User Documentation" tile linking to Getting Started, Tutorials, FAQ, and Reference pages
+
+2. **Workspace Navigation Hubs**
+   - Build navigation dashboards that organize content into logical categories
+   - Guide users to relevant content areas within extensive page structures
+   - Example: A project workspace with tiles for "Planning", "Execution", "Reporting", each linking to related pages
+
+3. **Content Organization and Structure**
+   - Create visual hierarchies for complex content structures
+   - Organize related pages under thematic categories
+   - Example: An onboarding page with tiles for different department introductions
+
+4. **Landing Page Design**
+   - Design attractive landing pages with multiple navigation tiles
+   - Combine multiple widget instances with different colors and icons to create a dashboard-like experience
+   - Example: A company intranet homepage with tiles for HR, IT Support, News, and Resources
+
+### Problem Statement
+
+**Problem Solved:** In extensive cplace workspaces with many pages and complex hierarchies, users struggle to find and navigate to relevant content. Traditional navigation methods (breadcrumbs, page trees) can be overwhelming or buried in the interface.
+
+**Solution:** The Documentation Navigation Widget provides visually distinct, prominently placed navigation tiles that act as clear signposts. The combination of color, icon, and organized page links makes navigation intuitive and reduces cognitive load.
+
+---
+
+## 3. Configuration Concepts
+
+### Configuration Attributes
+
+The widget is configured through the `NAVIGATION_WIDGET` type definition with the following attributes:
+
+#### 1. Title Text (`cf.cplace.documentation.titleText`)
+- **Type:** Single String (optional)
+- **Purpose:** Display text for the widget's main heading
+- **Multiplicity:** Maximum one
+- **Example:** "Getting Started", "User Documentation", "Project Resources"
+
+#### 2. Title Page (`cf.cplace.documentation.titlePage`)
+- **Type:** Single Page Reference (optional)
+- **Purpose:** Makes the title clickable and links to a target page
+- **Multiplicity:** Maximum one
+- **Behavior:** If configured, the title becomes a hyperlink; otherwise, it displays as plain text
+- **Use Case:** Link the title to an overview or main page for the category
+
+#### 3. Pages (`cf.cplace.documentation.pages`)
+- **Type:** Multi Page Reference
+- **Purpose:** Collection of pages displayed as navigation buttons below the title
+- **Multiplicity:** Multiple (any number)
+- **Rendering:** Each page appears as a flat button with white border
+- **Display:** Shows page name, truncated if necessary (max 200px width)
+
+#### 4. Icon (`cf.cplace.documentation.icon`)
+- **Type:** Single String with Icon Constraint
+- **Purpose:** Visual identifier displayed on the left side of the widget
+- **Default Value:** `cf-cplace`
+- **Supported Formats:**
+  - FontAwesome icons (prefix: `fa-`)
+  - cplace custom icons (prefix: `cf-`)
+- **Example Values:** `fa-book`, `fa-graduation-cap`, `cf-cplace`, `fa-wrench`
+
+#### 5. Color (`cf.cplace.landingPage.color`)
+- **Type:** Text Enumeration (optional)
+- **Purpose:** Background color scheme for the widget tile
+- **Multiplicity:** Maximum one
+- **Available Options:** 24 Material Design-inspired colors including:
+  - Primary colors: Red, Blue, Green, Yellow, Orange, Pink, Purple
+  - Variants: Dark-Red, Light-Blue, Dark-Blue, Light-Green, Dark-Green
+  - Neutral: Grey, Blue-Grey, Brown, White
+  - Additional: Indigo, Cyan, Teal, Lime, Amber, Deep-Orange, Deep-Purple
+- **Visual Effect:** The color affects both the widget background and icon tile shading
+
+### Configuration Behavior
+
+- **Title Display Logic:** The widget intelligently handles three scenarios:
+  1. Both `titleText` and `titlePage` configured: Displays clickable title text linking to the page
+  2. Only `titlePage` configured: Displays the page name as a clickable link
+  3. Only `titleText` configured: Displays plain text title (not clickable)
+
+- **Icon Processing:** The template automatically prepends the appropriate CSS class prefix (`fa` or `cf`) based on the first two characters of the icon value
+
+- **Color Scheme:** Each color option provides:
+  - Main background color (500 shade from Material Design palette)
+  - Icon tile background (400 shade)
+  - Icon color (500 shade)
+  - Hover effects on page buttons
+
+---
+
+## 4. Context and Relationships
+
+### Plugin Context
+
+The widget is part of the **cf.cplace.documentation** plugin, which is described as supporting "the creation of clear entry pages for easier navigation in extensive page structures through the free configurability of titles and page links."
+
+**Plugin Details:**
+- **Display Name:** cplace Documentation
+- **Group:** cf.cplace
+- **Repository:** cplace-paw (Platform Add-on Widgets)
+- **Icon:** fa-info
+
+### Related Widgets
+
+The Documentation Navigation Widget is part of a broader ecosystem of landing page and navigation widgets in cplace:
+
+1. **Landing Page Widgets** (cf.cplace.landingPageFromPage plugin):
+   - `cf.cplace.landingPageFromPage.quickOverview` - Quick overview displays
+   - `cf.cplace.landingPageFromPage.sessionUserNameWidget` - Welcome messages
+   - `cf.cplace.landingPageFromPage.simpleListWithAttachment` - List displays with attachments
+
+2. **Navigation Widgets**:
+   - `cf.cplace.breadcrumbs.breadcrumbsWidget` - Breadcrumb navigation
+   - `cf.cplace.navigationTileWidget.widget` - Alternative navigation tile
+
+### Widget Positioning in Ecosystem
+
+- **Category:** Navigation and Documentation widgets
+- **Complexity Level:** Medium (requires understanding of page references and visual design)
+- **Target Users:** Workspace administrators, content managers, documentation creators
+- **Typical Page Types:** Landing pages, dashboard pages, portal entry pages
+
+### Prerequisites and Dependencies
+
+- **Dependencies:** Only requires cf.cplace.platform (core platform)
+- **Page Requirements:** Works on any page where widgets can be placed
+- **Content Requirements:** Benefits from having multiple related pages to link to
+- **User Permissions:** Users viewing the widget need read access to referenced pages
+
+---
+
+## 5. Visual Design and Styling
+
+### Layout Structure
+
+```
+┌─────────────────────────────────────────────┐
+│ [Icon Tile]  Main Title (clickable)         │
+│   [Icon]                                     │
+│   80x100%    [Button] [Button] [Button]     │
+│              [Button] [Button]               │
+└─────────────────────────────────────────────┘
+```
+
+### Key Styling Features
+
+1. **Widget Container:**
+   - Rounded corners (10px border-radius)
+   - Minimum height: 155px
+   - Colored background based on selected color scheme
+   - No frame or padding around the widget itself
+
+2. **Icon Tile:**
+   - Fixed width: 80px
+   - Height: Full widget height
+   - Positioned on the left side
+   - Rounded corners (10px)
+   - Slightly lighter shade than main background
+   - Icon centered vertically
+
+3. **Title:**
+   - Large font size (2em)
+   - White color
+   - Text truncation with ellipsis if too long
+   - Positioned at the top with 13px padding
+
+4. **Page Buttons:**
+   - Flat style with white border
+   - White text on transparent background
+   - Hover effect: white background with colored text
+   - Maximum width: 200px with text truncation
+   - Spacing: 13px margin bottom, 6.5px margin right
+   - Padding: 6px vertical, 20px horizontal
+
+### CSS Classes
+
+- `.cf-cplace-documentation-wrapper` - Outer container
+- `.cf-cplace-documentation-widget-row` - Main widget row with color variants
+- `.icon-tile` - Icon container
+- `.sub-pages` - Container for page link buttons
+- Color-specific classes: `.Red`, `.Blue`, `.Green`, etc.
+
+---
+
+## 6. Technical Details
+
+### Configuration Type Definition
+
+Located in: `cf.cplace.documentation.DocumentationWidgetTypes.NAVIGATION_WIDGET`
+
+```java
+public static final TypeDef TYPE = new TypeDef(
+    "cf.cplace.documentation.navigationWidget",
+    TITLE_TEXT,
+    TITLE_PAGE,
+    PAGES,
+    ICON,
+    COLOR
+);
+```
+
+### Template Substitutions
+
+The widget provides the following template substitutions:
+
+- `titleText` - The configured title text
+- `titlePageUrl` - Absolute URL of the title page
+- `titlePage` - Page object for the title link
+- `pages` - List of page references for navigation buttons
+- `icon` - Processed icon class string
+- `color` - Selected color scheme
+
+### Rendering Notes
+
+- Widget renders without a frame or padding for seamless integration into page layouts
+- Page names are displayed using `$p.name()$` template function
+- Page URLs are generated using `$p.url()$` for relative links and `getAbsoluteUrl()` for title pages
+- The template handles conditional rendering based on which fields are configured
+
+---
+
+## 7. Best Practices and Recommendations
+
+### Configuration Best Practices
+
+1. **Title Configuration:**
+   - Use clear, concise titles (2-4 words)
+   - Consider linking the title to an overview or index page
+   - Example: "User Guides" linking to a user guide overview page
+
+2. **Page Selection:**
+   - Limit to 5-8 page links for optimal readability
+   - Select pages of similar importance/hierarchy level
+   - Order pages logically (e.g., Getting Started → Intermediate → Advanced)
+
+3. **Color and Icon Selection:**
+   - Use colors consistently across related widgets
+   - Choose icons that clearly represent the content category
+   - Consider accessibility when selecting color combinations
+
+4. **Layout Design:**
+   - Combine multiple navigation widgets to create dashboard layouts
+   - Use different colors to visually distinguish different content areas
+   - Place on landing pages or workspace entry points
+
+### Common Patterns
+
+1. **Documentation Portal Pattern:**
+   - Multiple navigation widgets on one page
+   - Each widget represents a documentation category
+   - Different colors for different categories
+
+2. **Hierarchical Navigation Pattern:**
+   - Title links to parent/overview page
+   - Page links lead to child pages
+   - Creates clear parent-child relationship
+
+3. **Dashboard Pattern:**
+   - Grid layout of navigation widgets
+   - Each widget represents a functional area
+   - Consistent styling with varying colors and icons
+
+---
+
+## 8. Example Scenarios
+
+### Scenario 1: IT Support Portal
+
+**Configuration:**
+- **Title Text:** "IT Support"
+- **Title Page:** Link to IT Support Overview page
+- **Pages:**
+  - Request Access
+  - Report Issue
+  - FAQ
+  - Contact IT
+- **Icon:** fa-wrench
+- **Color:** Blue
+
+**Use Case:** Employees need quick access to IT support resources from the company intranet homepage.
+
+### Scenario 2: Project Documentation Hub
+
+**Configuration:**
+- **Title Text:** "Project Alpha Documentation"
+- **Title Page:** Link to Project Alpha main page
+- **Pages:**
+  - Project Charter
+  - Requirements
+  - Architecture
+  - Meeting Notes
+  - Deliverables
+- **Icon:** fa-folder-open
+- **Color:** Green
+
+**Use Case:** Project team members need organized access to all project documentation from the project workspace.
+
+### Scenario 3: Employee Onboarding
+
+**Configuration:**
+- **Title Text:** "Welcome to the Team!"
+- **Title Page:** Link to Welcome page
+- **Pages:**
+  - First Day Checklist
+  - Company Policies
+  - Benefits Information
+  - Team Directory
+  - Training Schedule
+- **Icon:** fa-graduation-cap
+- **Color:** Purple
+
+**Use Case:** New employees need a clear starting point with organized access to onboarding materials.
+
+---
+
+## 9. Limitations and Considerations
+
+### Current Limitations
+
+1. **Fixed Layout:**
+   - Icon position is fixed on the left
+   - Layout is not configurable (always horizontal with icon left, content right)
+   - No option for vertical layouts or alternative arrangements
+
+2. **Button Display:**
+   - Page buttons are simple flat buttons with limited styling options
+   - No option for custom button colors or icons
+   - Button text truncation at 200px may cut important information
+
+3. **Title Constraints:**
+   - Single-line title with text truncation
+   - No subtitle or description field
+   - Limited typography options
+
+4. **Color Limitations:**
+   - Color applies to entire widget
+   - No option for custom color values (limited to 24 predefined colors)
+   - Color attribute references `cf.cplace.landingPage.color` (suggests possible refactoring artifact)
+
+### Performance Considerations
+
+- Minimal performance impact (static rendering, no dynamic JavaScript)
+- Page reference resolution happens during rendering
+- Suitable for dashboards with many instances
+
+### Accessibility Considerations
+
+- Color should not be the only means of differentiation
+- Consider contrast ratios when selecting colors
+- Ensure page link text is descriptive enough for screen readers
+
+---
+
+## 10. Summary
+
+### Key Takeaways
+
+1. **Primary Purpose:** Create visual navigation entry points with styled tiles combining titles, page links, and icons
+
+2. **Main Benefits:**
+   - Improves navigation in complex page structures
+   - Provides clear visual hierarchy
+   - Reduces cognitive load through organized presentation
+   - Enhances landing page aesthetics
+
+3. **Ideal For:**
+   - Documentation portals and hubs
+   - Landing pages and dashboards
+   - Workspace entry points
+   - Content organization and navigation
+
+4. **Configuration Simplicity:**
+   - Medium complexity
+   - Requires understanding of page references
+   - Visual configuration (color, icon) is straightforward
+   - Flexible title configuration options
+
+### Integration with cplace
+
+This widget exemplifies cplace's approach to low-code page design, allowing administrators to create professional, functional navigation interfaces without custom development. It fits into the broader ecosystem of landing page and navigation widgets that enable users to build intuitive, visually appealing workspace entry points.
+
+---
+
+## Source Files
+
+- **Widget Definition:** `/cf.cplace.documentation/src/main/java/cf/cplace/documentation/script/DocumentationWidgetDefinition.java`
+- **Configuration Types:** `/cf.cplace.documentation/src/main/java/cf/cplace/documentation/DocumentationWidgetTypes.java`
+- **Template:** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/script/documentationWidgetDefinition.htm`
+- **Styling:** `/cf.cplace.documentation/assets/less/plugin.less`
+- **Messages (EN):** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/messages_en.properties`
+- **Messages (DE):** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/messages_de.properties`