@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-lowcode-ai-chatWidget/research.md

@@ -0,0 +1,194 @@
+# Chat Widget Research (`cf.cplace.lowcode.ai.chatWidget`)
+
+## Widget Overview
+
+The Chat Widget provides an embeddable AI-powered chat interface that allows users to interact with AI assistants through natural language conversations. It enables low-code developers to create custom conversational AI experiences by configuring a CplaceJS script that defines the chat behavior and access control.
+
+**Widget ID:** `cf.cplace.lowcode.ai.chatWidget`
+**Repository:** `cplace-citizen-ai`
+**Definition Class:** `cf.cplace.citizenAi/src/main/java/cf/cplace/citizenAi/widgets/ChatWidgetDefinition.java`
+
+---
+
+## Purpose and Core Functionality
+
+### What This Widget Does
+
+The Chat Widget embeds a chat interface on cplace pages where users can have conversational interactions with an AI assistant. The widget:
+
+1. **Displays a chat UI** - Uses a frontend web component (`cf-lowcode-ai`) to render the chat interface
+2. **Executes custom business logic** - Runs a CplaceJS script on each user message that defines how the AI responds
+3. **Persists conversations** - Stores chat history using `PersistentAiChatMemory`, either per-user or shared across all users
+4. **Provides page context** - Makes the embedding page, search results, and selected pages available to the script
+
+### Technical Architecture
+
+```
+User Input → Chat Widget Frontend (Angular)
+           → REST Endpoint (/chat/messages)
+           → ChatService.postMessage()
+           → ChatWidgetScriptExecutionProcessor.execute()
+           → CplaceJS Script (call() function)
+           → CitizenAiAssistant.generate()
+           → AI Model Response
+           → Persisted to Memory
+           → Response to Frontend
+```
+
+---
+
+## Use Cases
+
+### When to Use This Widget
+
+1. **Custom AI Chat Assistants** - Create page-specific AI assistants that can answer questions about projects, summarize data, or provide contextual help based on the page content
+
+2. **Data-Driven Conversations** - Build chat interfaces that can query and reason about pages retrieved from searches or connected tables, enabling users to ask questions about collections of data
+
+3. **Guided User Interactions** - Use prompt suggestions to guide users toward common questions or actions, making the AI more discoverable and useful
+
+4. **User-Specific vs. Shared Conversations** - Support both individual chat histories (each user sees their own conversation) or shared chat rooms (all users see the same conversation)
+
+5. **AI-Assisted Page Operations** - Allow the assistant to perform actions on pages (read/write) through No-Code Tools configured on the AI Assistant
+
+### Example Scenarios
+
+- **Project Dashboard Chat**: A project manager views a project page and asks the AI to "summarize the open high risks" - the AI analyzes related risk pages and provides a summary
+- **Document Q&A**: Users ask questions about documents embedded or linked to a page
+- **Status Reports**: Users request "create a management summary" and the AI generates a report based on configured data sources
+- **Interactive Help**: Domain-specific help that understands the context of the current page
+
+---
+
+## Configuration Concepts
+
+### Required Configuration
+
+| Configuration | Description |
+|--------------|-------------|
+| **Script** | CplaceJS script containing `checkAccess()` and `call()` functions (required) |
+
+### Core Configuration Options
+
+| Configuration | Type | Default | Description |
+|--------------|------|---------|-------------|
+| `showFrame` | Boolean | `false` | Whether to show the widget frame/border |
+| `localizedTitle` | Localized String | (default) | Title displayed in the widget header |
+| `isUserSpecificChat` | Boolean | `true` | If true, each user has their own chat history; if false, all users share the same conversation |
+| `maxMessages` | Number | `30` | Maximum messages retained in chat memory |
+| `showToolExecutions` | Boolean | `true` | Whether to display tool execution details in the UI |
+| `disclaimer` | Localized String | (default) | Disclaimer text shown in the chat interface |
+| `height` | Number | `500` | Widget height in pixels |
+
+### Data Source Configuration
+
+The widget supports configuring data sources that determine which pages are available to the script:
+
+| Option | Description |
+|--------|-------------|
+| **Search** | Pages from a configured search query (default) |
+| **Selection** | Explicitly selected pages |
+| **Connected Table** | Pages from a connected table widget |
+| `includeAllSearchResults` | Boolean to include all search results (not just paginated subset) |
+
+### Script Structure
+
+The CplaceJS script must return an object with specific functions:
+
+```javascript
+return {
+    // Required: Determines if the current user can use the chat
+    checkAccess: function() {
+        return true; // or false to disable
+    },
+
+    // Optional: Provide suggested prompts to users
+    suggestPrompts: function() {
+        return [{
+            "label": "My Project Status",
+            "icon": "fa-traffic-light",    // optional
+            "color": "#112233",            // optional
+            "prompt": 'Summarize the project...'
+        }];
+    },
+
+    // Required: Contains the actual business logic
+    call: function() {
+        const assistant = cplace.actions("cf.cplace.citizenAi")
+            .createAssistant(embeddingPage.getSpace(), "default", memory);
+        assistant.generate(userInput);
+    }
+}
+```
+
+### Script Bindings (Available Variables)
+
+| Binding | Type | Description |
+|---------|------|-------------|
+| `userInput` | String | The message text entered by the user |
+| `memory` | AiChatMemory | The persistent chat memory for context |
+| `pages` | Iterable\<WrappedPage\> | Pages from the configured data source |
+| `searchResults` | Iterable\<WrappedCustomEntity\> | All search results (if `includeAllSearchResults` is true) |
+| `embeddingPage` | WrappedPage | The page where the widget is embedded |
+
+---
+
+## Related Widgets and Context
+
+### Related Widget: Ask Your Page (`cf.cplace.citizenAi.askYourPageWidget`)
+
+- Simpler variant without script configuration
+- Provides pre-configured "Ask Your Page" functionality
+- Requires feature to be enabled in plugin settings
+- Same frontend component (`cf-wc-bridge` with `cf-lowcode-ai`)
+
+### Relationship to AI Assistants
+
+The Chat Widget works with **AI Assistant Configuration** pages:
+- Assistants are created via `cplace.actions("cf.cplace.citizenAi").createAssistant()`
+- Assistants can be configured with:
+  - Model ID (specifies which AI model to use)
+  - System message (defines the AI's persona/behavior)
+  - No-Code Tools (actions the AI can take)
+  - Temperature, max tokens, seed parameters
+
+### Dependencies
+
+| Dependency | Description |
+|------------|-------------|
+| Citizen AI Plugin | Core plugin providing AI functionality |
+| Low-Code permission | Required to embed and configure the widget |
+| AI Assistant Configuration | Optional - assistants can be created programmatically or from configuration pages |
+| Frontend Package | `@cplace-lowcode-ai-fe/cf-lowcode-ai` Angular web component |
+
+---
+
+## Permission Requirements
+
+1. **Embedding**: Only users with "Low-Code" edit permission can embed the widget
+2. **Access Control**: The `checkAccess()` function in the script determines runtime access
+3. **Space Embedding**: Widget can only be embedded in pages within spaces where the Citizen AI app is present
+4. **Script Visibility**: The script attribute is only visible in edit mode to users with Low-Code permission
+
+---
+
+## Key Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `ChatWidgetDefinition.java` | Widget definition, configuration, and content rendering |
+| `AiWidgetTypes.java` | Configuration attribute definitions |
+| `ChatWidgetScriptUtils.java` | Creates script engine with bindings |
+| `ChatWidgetScriptExecutionProcessor.java` | Executes the CplaceJS script |
+| `ChatService.java` | REST service handling message operations |
+| `ChatWidgetContextualHelp.java` | Contextual help for the script attribute |
+| `chatWidgetDefinition.htm` | Frontend template with web component bridge |
+| `getHelpMarkup.htm` | Script template documentation |
+| `LowcodeAiActions.java` | API for creating assistants from scripts |
+| `CitizenAiAssistant.java` | AI assistant implementation with tool support |
+
+---
+
+## Summary
+
+The Chat Widget is a flexible, script-driven widget for embedding AI chat functionality into cplace pages. It provides a low-code approach to building custom AI assistants by allowing developers to write CplaceJS scripts that define the chat behavior while leveraging the platform's AI infrastructure (model connections, memory persistence, tool execution). The widget is suitable for scenarios requiring contextual AI assistance, data-driven Q&A, or interactive AI-powered features within the cplace application.

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

@@ -0,0 +1,208 @@
+# Widget Research: cf.cplace.meeting.pageHeader
+
+## Widget Identification
+
+- **Widget ID**: `cf.cplace.meeting.pageHeader`
+- **Widget Name**: Meeting Details
+- **Repository**: cplace-paw
+- **Plugin**: cf.cplace.meeting
+- **Definition Class**: `cf.cplace.meeting.script.MeetingPageHeaderWidgetDefinition`
+
+## Purpose
+
+The Meeting Details widget displays comprehensive meeting/appointment information in a structured header format, showing time, location, participants (organizer, required and optional attendees), and providing quick access to edit attendees and export the meeting to Outlook calendar format (.ics file).
+
+## Overview
+
+This widget serves as the primary information display for appointment pages within the cplace Meetings app. It renders meeting metadata in a visually organized layout without a frame, providing an at-a-glance view of all essential meeting details along with actionable links for editing and calendar export.
+
+## Use Cases
+
+### Primary Use Case: Appointment Page Header
+The widget is automatically embedded as the default page header for all appointment pages (type `cf.appointment`) within the Meetings app. It provides users with:
+
+1. **Meeting Overview Display**
+   - Shows start and end dates with day-of-week formatting
+   - Displays meeting location
+   - Shows organizer information with profile image
+   - Lists required and optional attendees with profile images
+
+2. **Meeting Management Actions**
+   - Edit Attendees: Quick access to modify required and optional attendees
+   - Calendar Export: Download meeting as .ics file for Outlook/calendar integration
+
+3. **Visual Organization**
+   - Color-coded participant roles (organizer, required, optional)
+   - Profile images for all participants
+   - Structured layout with clear sections
+
+### Typical User Scenarios
+
+**Scenario 1: Viewing Meeting Details**
+- User opens an appointment page
+- Widget displays all meeting information at the top
+- User can quickly see who is invited, when the meeting is, and where it takes place
+
+**Scenario 2: Managing Attendees**
+- User clicks "Edit Attendees" link in the widget
+- Modal opens allowing modification of required/optional attendees
+- Changes are saved and widget updates to reflect new attendee list
+
+**Scenario 3: Calendar Integration**
+- User clicks the Outlook/calendar download link
+- Widget generates .ics file with meeting details
+- User imports file into their personal calendar application
+
+## Data Model Integration
+
+The widget integrates with the **APPOINTMENT** type (`cf.appointment`) which includes:
+
+### Required Attributes
+- **Subject** (`cf.appointmentSubject`): Meeting title
+- **Organizer** (`cf.appointmentOrganizer`): Person reference for meeting organizer
+- **Start Date** (`cf.appointmentDtstart`): Meeting start date
+- **Start Time** (`cf.appointmentDtstartTime`): Meeting start time (HH:mm format)
+- **End Date** (`cf.appointmentFinish`): Meeting end date
+- **End Time** (`cf.appointmentEndTime`): Meeting end time (HH:mm format)
+
+### Optional Attributes
+- **Required Attendees** (`cf.appointmentReqAttendees`): Multi-person reference
+- **Optional Attendees** (`cf.appointmentOptAttendees`): Multi-person reference
+- **Location** (`cf.appointmentLocation`): String value for meeting location
+- **Summary** (`cf.appointmentSummary`): Rich text description/agenda
+- **Minutes** (`cf.appointmentMinutes`): Rich text for meeting notes
+
+## Configuration Concepts
+
+### Widget Behavior
+- **Frame Display**: The widget renders without a frame (`showFrame() = false`)
+- **Scope Object**: Uses the appointment page as the scope object
+- **Initialization**: Widget automatically binds to the appointment page it's embedded in
+
+### No User-Configurable Options
+This widget does not expose configuration parameters. It operates with a fixed behavior:
+- Automatically displays all appointment attributes
+- Links are generated based on the current page context
+- Styling is controlled by the plugin's LESS stylesheet
+
+### Template Substitutions
+The widget provides the following data to its template:
+- `editAttendeesUrl`: URL for editing attendees
+- `dtStartDateWithWeekDay`: Formatted start date with weekday name
+- `dtFinishDateWithWeekDay`: Formatted end date with weekday name
+- `downloadAsCalFileUrl`: URL for downloading .ics file
+- `organizerImage`: Profile image URL for organizer
+- `organizerName`: Name of the organizer
+- `reqAttendees`: List of required attendees with image and name
+- `optAttendees`: List of optional attendees with image and name
+
+## Related Components
+
+### Related Handlers
+1. **EditHandler** (`cf.cplace.meeting.handler.EditHandler`)
+   - Provides editing interface for meeting attendees
+   - Accessed via "Edit Attendees" link in widget
+   - Requires edit permissions on the appointment page
+
+2. **DownloadAsCalFileHandler** (`cf.cplace.meeting.handler.DownloadAsCalFileHandler`)
+   - Generates iCalendar (.ics) file from appointment data
+   - Includes all meeting details, attendees, and links
+   - Accessed via "Open in Outlook" link in widget
+
+### Default Page Layout
+The widget is part of the default layout for appointment pages:
+```
+Row 1:
+  Column 1 (8 units):
+    - Meeting Page Header Widget (this widget)
+    - Minutes (rich text attribute widget)
+  Column 2 (4 units):
+    - Files Widget
+    - Comments Widget
+```
+
+### Styling
+- Custom CSS class: `.cf-cplace-meeting-headerPage-widget-body`
+- Branded colors based on plugin theme (`@meeting-plugin-base-color`)
+- Responsive design with mobile breakpoint at 991px
+- Visual distinction for organizer (gray), required attendees (green), optional attendees (blue)
+
+## Technical Details
+
+### Widget Definition Location
+- File: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/script/MeetingPageHeaderWidgetDefinition.java`
+- Package: `cf.cplace.meeting.script`
+- Extends: `WidgetDefinition`
+
+### Internationalization
+- Widget name and description defined in: `cf/cplace/meeting/messages_en.properties`
+- English name: "Meeting Details"
+- English description: "Displays meeting details such as time, location, participants and agenda."
+- Additional message keys for labels (organizer, required, optional, location, etc.)
+
+### Date Formatting
+- Uses `InternalDateFormats.NAME_OF_DAY` for displaying dates with weekday names
+- Respects user locale for date formatting (`SessionLocal.getUserLocale()`)
+
+### Person/User Integration
+- Works specifically with `Person` entities for organizer and attendees
+- Displays profile images using `FunctionsHelper.proxy("profileImgUrl", person)`
+- Falls back to empty string if reference is not a Person entity
+
+## Dependencies
+
+### Plugin Dependencies
+- **cf.cplace.platform** (version 25.3.80): Core platform functionality
+
+### App Context
+Part of the **Meetings** app (`cf.cplace.meeting.MeetingApp`):
+- App display name: "Meetings"
+- App icon: `fa-calendar`
+- App description: "With the 'Meetings' app, you can create appointments as pages and keep minutes. You can download the appointments as .ics files to send them or save them in your personal calendar."
+
+## Usage Constraints
+
+### Prerequisites
+1. The Meetings app must be installed and enabled in the workspace
+2. Appointment type must be available
+3. User must have read permissions on the appointment page
+
+### Limitations
+1. Widget only works on appointment pages (type `cf.appointment`)
+2. Returns `null` for meeting if embedded entity is not a Page
+3. No configuration options - fixed behavior
+4. Requires Person entities for proper attendee display
+
+## Key Features Summary
+
+1. **Comprehensive Meeting Information Display**
+   - All critical meeting data in one place
+   - Formatted dates with weekday names
+   - Visual participant organization
+
+2. **Quick Actions**
+   - One-click access to edit attendees
+   - Direct calendar export functionality
+
+3. **Visual Design**
+   - Profile images for human context
+   - Color-coded participant roles
+   - Responsive layout for mobile devices
+
+4. **Integration**
+   - Seamlessly works with Person directory
+   - Calendar file export for external tool integration
+   - Locale-aware date formatting
+
+## Code References
+
+### Key Files
+- Widget Definition: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/script/MeetingPageHeaderWidgetDefinition.java:30`
+- Type Definition: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/MeetingAppTypes.java:31`
+- Edit Handler: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/handler/EditHandler.java:16`
+- Calendar Export Handler: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/handler/DownloadAsCalFileHandler.java:21`
+- Styling: `/cf.cplace.meeting/assets/less/plugin.less:11`
+
+### Default Widget Inclusion
+The widget is included by default in the appointment type definition at:
+`/cf.cplace.meeting/src/main/java/cf/cplace/meeting/MeetingAppTypes.java:115`

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

@@ -0,0 +1,259 @@
+# Navigation Tile Widget Research
+
+## Widget Identification
+
+- **Widget ID**: `cf.cplace.navigationTileWidget.widget`
+- **Repository**: `cplace-paw`
+- **Plugin Name**: `cf.cplace.navigationTileWidget`
+- **Definition Class**: `NavigationTileWidgetDefinition.java`
+
+---
+
+## 1. Purpose & Description
+
+### One-Sentence Description
+The Navigation Tile Widget displays clickable tiles representing pages in a workspace hierarchy, enabling users to navigate between related pages without using the workspace navigation menu.
+
+### Detailed Description
+The Navigation Tile Widget (Kachel-Navigation) provides a visual, icon-based navigation interface that displays a reference page and its child pages as clickable tiles. Each tile shows the page's icon and name, allowing users to quickly switch between pages in a page hierarchy. The widget automatically highlights the currently active page and adapts its display for different screen sizes (desktop shows tiles, mobile shows a dropdown menu).
+
+---
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Page Hierarchy Navigation**
+   - Display a parent page and all its child pages as navigation tiles
+   - Allow users to navigate between sibling pages without returning to the workspace navigation
+   - Useful for dashboards, overview pages, or section landing pages
+
+2. **Section Navigation**
+   - Create a consistent navigation bar across multiple related pages
+   - Navigate between pages at the same level in the hierarchy
+   - Maintain context within a specific section of the workspace
+
+3. **Workspace Homepage Navigation**
+   - Display top-level sections of a workspace from the root page
+   - Provide quick access to main workspace areas
+   - Alternative to traditional menu-based navigation
+
+4. **Embedded Page Navigation**
+   - Navigate between pages that are related to the current page context
+   - Show navigation options that are contextually relevant to the embedding page
+
+### When to Use This Widget
+
+- When you have a group of related pages that users frequently navigate between
+- When you want to provide visual, icon-based navigation instead of text-based menus
+- When building section-based workspaces with clear page hierarchies
+- When you need navigation that adapts to mobile devices (tiles on desktop, dropdown on mobile)
+
+### When NOT to Use This Widget
+
+- For deep navigation hierarchies (more than 2-3 levels)
+- When you have many pages at the same level (tiles work best with 3-8 items)
+- For navigation that doesn't follow the page hierarchy structure
+- When standard workspace navigation is sufficient
+
+---
+
+## 3. Core Functionality
+
+### How It Works
+
+1. **Reference Page Selection**: The widget takes a reference page as the starting point
+2. **Tile Generation**: It displays tiles for:
+   - The reference page itself (optional, based on configuration)
+   - All child pages of the reference page that are marked to "Show in tile navigation"
+3. **Active State**: The currently viewed page is highlighted with visual styling
+4. **Responsive Display**:
+   - Desktop/tablet: Shows tiles in a horizontal row
+   - Mobile: Shows as a dropdown menu with the current page name
+
+### Page Visibility Control
+
+Pages must be explicitly marked to appear in the navigation:
+- Each page has a boolean attribute: "Show in tile navigation" (`cf.cplace.navigationTileWidget.showInNavigationWidget`)
+- Only pages with this flag set to `true` will appear as tiles
+- This gives fine-grained control over which pages are included
+
+---
+
+## 4. Configuration Options
+
+### Main Configuration Parameters
+
+#### 1. Reference Page (`reference_page`)
+**Purpose**: Determines the starting point for generating navigation tiles.
+
+**Options**:
+- **Parent page** (default): Uses the parent of the embedding page as reference
+  - Example: If widget is on page "Team A", it shows the parent's children (Team A, Team B, Team C)
+- **Workspace home**: Uses the root page of the workspace as reference
+  - Example: Shows top-level sections of the workspace
+- **Embedding page**: Uses the current page as reference
+  - Example: If widget is on page "Products", it shows children of "Products"
+
+**Use Case Guidance**:
+- Use "Parent page" for sibling navigation (most common)
+- Use "Workspace home" for consistent top-level navigation across all pages
+- Use "Embedding page" for sub-section navigation
+
+#### 2. Include Reference Page (`includeReferencePage`)
+**Purpose**: Controls whether the reference page itself appears as a tile.
+
+**Options**:
+- `true` (default): The reference page is included as a tile
+- `false`: Only child pages are shown as tiles
+
+**Use Case Guidance**:
+- Set to `true` when the reference page is a valid navigation target (e.g., "Overview" page)
+- Set to `false` when the reference page is purely organizational (not meant to be visited)
+
+---
+
+## 5. Technical Architecture
+
+### Page Attribute Extension
+
+The plugin extends the default page type with:
+- **Attribute**: `cf.cplace.navigationTileWidget.showInNavigationWidget` (boolean)
+- **Default Value**: `false`
+- **Purpose**: Opt-in mechanism for pages to appear in navigation tiles
+- **Visibility**: Hidden in attribute widgets and tables (internal configuration)
+
+### Widget Configuration Type
+
+The widget uses a custom configuration type (`NAVIGATION_TILE_WIDGET`) with:
+- `referencePage`: String enum (Parent/Root/Embedding)
+- `includeReferencePage`: Boolean with default `true`
+
+### Template & Display
+
+- **Desktop Display**: Horizontal row of square tiles (60x60px) with icons
+- **Mobile Display**: Dropdown menu with icon and page name
+- **Active State**: Visual highlighting with border and color change
+- **Styling**: Gradient backgrounds, hover effects, shadow effects
+
+---
+
+## 6. Context & Relationships
+
+### Related Features
+
+- **Page Hierarchy**: Depends on cplace's page parent-child relationships
+- **Workspace Navigation**: Provides an alternative to the standard workspace menu
+- **Page Icons**: Uses the icon configured for each page
+
+### Prerequisites
+
+- Pages must be organized in a hierarchical structure
+- Pages intended for navigation must have the "Show in tile navigation" flag enabled
+- The Navigation Tile Widget app must be enabled in the workspace
+
+### Dependencies
+
+- **Platform**: `cf.cplace.platform` (version 25.3.80+)
+- **Core Types**: Uses standard page types and page space functionality
+- **Icon Service**: Leverages platform icon service for displaying page icons
+
+---
+
+## 7. Implementation Details
+
+### Key Classes
+
+1. **NavigationTileWidgetDefinition**: Main widget definition
+   - Implements content substitution logic
+   - Handles reference page resolution
+   - Manages active tile state
+   - Provides responsive display logic
+
+2. **NavigationTileWidgetTypes**: Configuration type definitions
+   - Defines widget configuration attributes
+   - Provides enumeration values for reference page options
+
+3. **NavigationTileWidgetAppTypes**: Page type extension
+   - Adds "Show in tile navigation" attribute to pages
+
+### Logic Flow
+
+```
+1. Widget loads on a page (embedding page)
+2. Check if embedding page has "Show in Navigation Widget" flag
+3. Determine reference page based on configuration:
+   - Parent of embedding page
+   - Root page of workspace
+   - Embedding page itself
+4. Collect tiles:
+   - Add reference page if "Include Reference Page" is true
+   - Add all children of reference page with "Show in Navigation Widget" flag
+5. Determine active tile:
+   - For Parent/Embedding reference: active = embedding page
+   - For Root reference: active = page in path directly under root
+6. Render tiles with active state highlighting
+```
+
+### Display Behavior
+
+- **No Frame**: Widget renders without standard widget frame (`showFrame() = false`)
+- **No Padding**: Widget uses full width without padding (`isNoPadding() = true`)
+- **Responsive**: Template includes both desktop tile view and mobile dropdown view
+- **Icons**: Uses Font Awesome classes for page icons
+
+---
+
+## 8. Visual Design
+
+### Tile Appearance
+
+- **Size**: 60x60px square tiles
+- **Background**: Gradient from #878787 to #9e9e9e
+- **Icon**: 36px Font Awesome icon in yellow (#ffec00)
+- **Spacing**: 5px margin between tiles
+- **Effects**: Box shadow, transition effects on hover
+
+### Active State Styling
+
+- **Icon Color**: Changes to black for active tile
+- **CSS Class**: `.cf-aktiv` applied to active tile
+
+### Hover Effects
+
+- **Border**: Yellow border (#ffec00) appears on hover
+- **Transition**: 0.6s smooth transition for visual feedback
+
+### Mobile Dropdown
+
+- **Trigger**: Shows current page icon and name with caret
+- **Menu**: Standard Bootstrap dropdown with page list
+- **Active Item**: Highlighted with `.cf-aktiv` class
+
+---
+
+## 9. Localization
+
+The widget supports multiple languages (German and English):
+
+- **Widget Name**: "Tile Navigation" / "Kachel-Navigation"
+- **App Description**: "The Tile Navigation lets you switch from one cplace page to another, without having to use the workspace navigation menu."
+- **Configuration Labels**: All configuration options are localized
+
+---
+
+## 10. Testing Support
+
+The plugin includes a test handler (`NavigationTileTestHandler`) that:
+- Creates a test page hierarchy (root → sub1 → sub11)
+- Configures pages with the navigation widget
+- Enables the "Show in navigation widget" flag
+- Sets up widget configuration with parent page reference
+
+This demonstrates the typical setup pattern for the widget.
+
+---
+
+## Summary
+
+The Navigation Tile Widget is a visual navigation component that transforms page hierarchies into clickable tile interfaces. It's ideal for creating intuitive, icon-based navigation for related pages, with built-in responsive behavior and fine-grained control over which pages appear in the navigation. The widget works best for shallow hierarchies with 3-8 related pages and provides an alternative to traditional menu-based navigation.