@cplace/mcp-server 1.3.14

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.

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

@@ -0,0 +1,174 @@
+# Widget Research: cf.cplace.officeReports.headlineForReports
+
+## Overview
+
+**Widget ID:** `cf.cplace.officeReports.headlineForReports`
+
+**Repository:** `cplace-office-reports`
+
+**Definition Class:** `/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/HeadlineForReportsWidgetDefinition.java`
+
+## Purpose
+
+The `headlineForReports` widget displays a styled banner headline for Office Report Configuration pages. It provides visual identification of the report type (PowerPoint, Word, Excel, or Excel with Macros) through a color-coded header with an appropriate icon.
+
+**Short Description:** A visual banner widget that displays "cplace Office Report Configuration" as a styled headline with report-type-specific color coding and icons for Office Report Configuration pages.
+
+## Core Functionality
+
+### What It Does
+
+The widget:
+1. Displays a fixed headline text: "cplace Office Report Configuration"
+2. Applies report-type-specific styling (color and icon) based on the report configuration
+3. Determines the report type from the embedding page's `REPORT_TYPE` attribute
+4. Renders with no padding and no frame for a clean, banner-like appearance
+
+### Visual Appearance
+
+The widget renders as an 80px tall banner with:
+- **Height:** 80px, full width
+- **Background color:** Report-type specific (see styling section)
+- **Icon:** FontAwesome icon (60px) positioned on the left with 50% opacity
+- **Title:** White text "cplace Office Report Configuration" (40px font size)
+- **Layout:** Icon on left, title text aligned with padding from the icon
+
+### Report Type Styling
+
+The widget applies different colors and icons based on the report type:
+
+| Report Type | Background Color | Icon | Extensions |
+|-------------|-----------------|------|------------|
+| **PPT** | Orange-red (#d86245) | PowerPoint icon (\f1c4) | .ppt, .pptx |
+| **WORD** | Blue (#4d82b9) | Word icon (\f1c2) | .doc, .docx |
+| **EXCEL** | Green (#75a797) | Excel icon (\f1c3) | .xls, .xlsx |
+| **EXCEL_WITH_MACROS** | Green (#75a797) | Excel icon (\f1c3) | .xlsm |
+| **Unknown** | Gray (#f0f0f0) | Generic file icon (\f15b) | N/A |
+
+## Use Cases
+
+### Primary Use Case: Report Configuration Page Identification
+
+The widget serves as a visual header for Office Report Configuration pages, helping users immediately identify:
+- That they are working with an Office Report configuration
+- The type of report they are configuring (PowerPoint, Word, or Excel)
+
+### Specific Scenarios
+
+1. **PowerPoint Report Configuration**
+   - User creates a PowerPoint report configuration
+   - Widget displays with orange-red background and PowerPoint icon
+   - Provides visual confirmation of report type selection
+
+2. **Word Report Configuration**
+   - User creates a Word report configuration
+   - Widget displays with blue background and Word icon
+   - Helps distinguish Word reports from other types
+
+3. **Excel Report Configuration**
+   - User creates an Excel report configuration
+   - Widget displays with green background and Excel icon
+   - Works for both standard Excel (.xlsx) and macro-enabled Excel (.xlsm)
+
+4. **New Report Configuration (Unknown Type)**
+   - User creates a new report configuration without selecting a type
+   - Widget displays with gray background and generic file icon
+   - Indicates that report type needs to be configured
+
+## Configuration Concepts
+
+### Embedding Restrictions
+
+The widget can **only** be embedded in:
+- Pages of custom type: `cf.cplace.officeReports.configuration` (Report Configuration type)
+- Type definition layouts for the Report Configuration type
+
+Attempting to embed it elsewhere will throw a `NotEmbeddableException` with the message:
+> "Headline for report widget only embeddable in pages of type cf.cplace.officeReports.configuration"
+
+### Configuration Parameters
+
+The widget has **no user-configurable parameters**. Its behavior is entirely determined by:
+- The embedding page's `REPORT_TYPE` attribute value
+- Fixed styling rules based on report type
+
+### Layout Integration
+
+In the standard Report Configuration layout, the widget:
+- Occupies the first row (full width, 12 columns)
+- Appears above all other configuration widgets
+- Is positioned before the Settings and Script sections
+- Has `isNoPadding()` set to true and `showFrame()` set to false for seamless integration
+
+## Context and Relationships
+
+### Parent Feature: Office Reports
+
+The widget is part of the **cplace Office Reports** plugin, which provides functionality for:
+- Generating Office documents (PowerPoint, Word, Excel) from cplace data
+- Configuring report templates with placeholders
+- Scripting dynamic content for reports
+- Attaching generated reports to pages
+
+### Related Widgets in Report Configuration
+
+The Report Configuration page layout includes several complementary widgets:
+
+1. **cf.cplace.officeReports.headlineForReports** (this widget)
+   - Purpose: Visual header/banner
+
+2. **cf.cplace.officeReports.templatePlaceholders**
+   - Purpose: Displays available placeholders from the report template
+   - Position: Bottom left section of the layout
+
+3. **cf.cplace.officeReports.scriptPlaceholders**
+   - Purpose: Displays placeholders defined in the report script
+   - Position: Bottom right section of the layout
+
+4. **Attributes Groups**
+   - Settings group: Name, Report Identifier, Report Template, Attachment configuration
+   - Script group: Script editor for report generation logic
+
+### Dependencies
+
+The widget depends on:
+- **OfficeReportsAppTypes.REPORT_CONFIGURATION**: Provides the Report Configuration type definition and REPORT_TYPE attribute
+- **ReportType enum**: Defines the available report types (PPT, WORD, EXCEL, EXCEL_WITH_MACROS)
+- **WidgetPrinting.getEmbeddingEntity()**: Retrieves the page context to determine report type
+
+## Technical Implementation Details
+
+### Template Processing
+
+The widget uses `WidgetTemplateSubstitution` to:
+1. Initialize by checking if it's embedded in a TypeDefinitionLayout or a Page
+2. Extract the embedding page's REPORT_TYPE attribute value
+3. Substitute the `$type$` variable in the HTML template with the report type name
+4. Return "unknown-report-type" if the page or report type is not found
+
+### Rendering Behavior
+
+- **Template file:** `headlineForReportsWidgetDefinition.htm`
+- **CSS class structure:** `cf-cplace-office-reports-headline-report-type` with report type as additional class
+- **No padding/frame:** Configured via `isNoPadding()` and `showFrame()` methods
+- **Title:** Uses the widget's name message (internationalized)
+
+### Frontend Styling
+
+Defined in: `/cf.cplace.officeReports/assets/less/plugin.less`
+
+Key styling features:
+- Fixed 80px height banner
+- Absolute positioned FontAwesome icon (left: 10px)
+- White text with truncation overflow handling
+- CSS classes use report type enum names (PPT, WORD, EXCEL, etc.)
+
+## Summary
+
+The `headlineForReports` widget is a specialized, non-configurable banner widget that provides visual branding and report-type identification for Office Report Configuration pages. It enhances user experience by:
+- Offering immediate visual feedback about the report type
+- Providing consistent branding across all report configurations
+- Using familiar Office application colors and icons
+- Seamlessly integrating into the report configuration layout
+
+The widget is tightly coupled to the Report Configuration page type and serves as a fixed UI element rather than a general-purpose widget.

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

@@ -0,0 +1,233 @@
+# Widget Research: cf.cplace.officeReports.scriptPlaceholders
+
+## Widget Summary
+
+**Widget ID:** `cf.cplace.officeReports.scriptPlaceholders`
+
+**Description:** The Script Placeholders widget displays and validates all placeholders defined in a report configuration script, showing their line numbers and whether they exist in the associated report template.
+
+## Purpose
+
+The Script Placeholders widget analyzes Low-Code scripts used for Office report generation and extracts all placeholder definitions. It provides developers and report designers with a comprehensive overview of:
+
+1. **Placeholder Definitions**: All placeholders defined using `report.put()` or `slide.put()` calls in the script
+2. **Line Numbers**: The exact line in the script where each placeholder is defined
+3. **Template Validation**: Whether each placeholder actually exists in the Office template (PowerPoint, Word, or Excel)
+4. **Dynamic Columns**: Special handling for dynamically-added table columns in Excel reports
+
+The widget serves as a development and quality assurance tool, helping users ensure consistency between their Low-Code scripts and Office templates.
+
+## Use Cases
+
+### 1. Report Development and Debugging
+When creating or modifying Office report configurations, developers need to ensure that:
+- All placeholders defined in the script have corresponding placeholders in the template
+- All template placeholders are being populated by the script
+- The script syntax is correct and parseable
+
+**Example Scenario**: A developer writes a PowerPoint report script that defines placeholders for `{companyName}`, `{projectTitle}`, and `{status}`. The Script Placeholders widget displays these three placeholders with line numbers and shows green checkmarks for those present in the template, alerting the developer if any are missing.
+
+### 2. Template-Script Synchronization
+When templates are updated or modified separately from scripts, the widget helps identify mismatches:
+- Placeholders removed from templates but still defined in scripts
+- Naming inconsistencies between script and template
+
+**Example Scenario**: A template designer renames `{projectName}` to `{projectTitle}` in a PowerPoint template. The Script Placeholders widget will show that the script's `projectName` placeholder is not present in the template, prompting the developer to update the script accordingly.
+
+### 3. Excel Dynamic Column Validation
+For Excel reports with dynamically generated columns (using `addColumn()` with placeholder syntax), the widget identifies these special placeholders:
+- Shows which placeholders are used as dynamic column headers
+- Validates that dynamic columns are properly defined in the script
+
+**Example Scenario**: An Excel report dynamically adds columns for each month using placeholders like `{january}`, `{february}`, etc. The widget displays these with a special "dynamic column" indicator, distinguishing them from regular placeholders.
+
+### 4. Script Parsing Error Detection
+If the script contains syntax errors or cannot be parsed, the widget displays error messages to help developers identify and fix issues.
+
+**Example Scenario**: A developer accidentally introduces a syntax error in the Low-Code script. Instead of failing silently during report generation, the Script Placeholders widget immediately shows a parsing error message, allowing quick identification and correction.
+
+### 5. Quality Assurance and Documentation
+The widget provides a live reference of all placeholders used in a report configuration:
+- Serves as documentation of what data the report expects
+- Helps QA teams verify report completeness
+- Assists in onboarding new developers to existing report configurations
+
+## Configuration
+
+### Widget Configuration Options
+
+The Script Placeholders widget has minimal configuration:
+
+- **Height** (`height`): The fixed height of the widget in pixels (default: 500.0)
+
+The widget does not require manual configuration of data sources or filters - it automatically:
+1. Listens for template placeholder data from its companion widget
+2. Parses the script from the report configuration page it's embedded in
+3. Cross-references script placeholders with template placeholders
+
+### Embedding Requirements
+
+**Strict Embedding Context**: This widget can ONLY be embedded in:
+- Pages of type `cf.cplace.officeReports.configuration` (Report Configuration)
+- Type definitions for Report Configuration types
+
+Any attempt to embed it elsewhere will result in a `NotEmbeddableException`.
+
+### No User Configuration
+
+The widget operates automatically without user interaction or configuration. It:
+- Automatically reads the script from the embedding page's `cf.cplace.officeReports.script` attribute
+- Automatically receives template placeholder data from the companion Template Placeholders widget
+- Automatically parses and displays results
+
+## Technical Details
+
+### Script Parsing Mechanism
+
+The widget uses the **esprima** JavaScript parser to analyze Low-Code scripts:
+
+1. **AST Parsing**: Parses the script into an Abstract Syntax Tree (AST)
+2. **Call Expression Detection**: Identifies `put()` method calls on objects
+3. **Placeholder Extraction**: Extracts the first argument (the placeholder key) from `put()` calls
+4. **Dynamic Column Detection**: Identifies `addColumn()` calls with placeholder syntax `{columnName}` in additional arguments
+
+**Supported Placeholder Patterns**:
+- **Literal strings**: `report.put("companyName", value)` → extracts `"companyName"`
+- **Variables**: `report.put(variableName, value)` → displays as `"(variable expression: variableName)"`
+- **Complex expressions**: `report.put(expr, value)` → displays as `"(variable expression)"`
+
+### Communication with Template Widget
+
+The widget operates in coordination with the Template Placeholders widget:
+
+1. **Event Listening**: Subscribes to `PlaceholdersCtrl.EVENT_TEMPLATE_PLACEHOLDERS_LOADED` events
+2. **Data Reception**: Receives template placeholder data including:
+   - Template placeholders (from PowerPoint shapes, Word bookmarks, Excel cells)
+   - Table/cell placeholders (for Excel table structures)
+   - Report type (PowerPoint, Word, or Excel)
+3. **Cross-Validation**: Compares script placeholders against template placeholders
+4. **Presentation Marking**: Sets `presentInTemplate` flag for each script placeholder
+
+### Display Components
+
+**Table Columns**:
+1. **Line Number**: The line in the script where the placeholder is defined
+2. **Placeholder**: The placeholder name (displayed as code)
+3. **Present in Template**: Visual indicators:
+   - ✓ Green checkmark: Placeholder exists in template
+   - ⚙ Code icon: Placeholder is a dynamic column
+   - (No icon): Placeholder not found in template
+
+**Sorting**: All three columns support sorting (ascending/descending)
+
+**Pagination**: Results are paginated with Previous/Next navigation when there are many placeholders
+
+### Error Handling
+
+The widget displays different status messages:
+
+- **Success**: Shows the placeholder table
+- **Parsing Error**: "Could not parse report script: [error details]"
+- **Template Error**: Propagates error message from Template Placeholders widget
+- **Missing Template**: "Please select a template"
+
+## Context and Relationships
+
+### Related Widgets
+
+1. **cf.cplace.officeReports.templatePlaceholders** (Template Placeholders Widget)
+   - **Relationship**: Companion widget that must be present
+   - **Data Flow**: Template widget loads first and broadcasts placeholder data
+   - **Purpose**: Displays placeholders found in the Office template (PowerPoint slides, Word bookmarks, Excel cells)
+
+2. **cf.cplace.officeReports.headlineForReports** (Visual: Office Report Type)
+   - **Relationship**: Sibling widget in the standard Report Configuration layout
+   - **Purpose**: Displays a visual indicator of the report type (PowerPoint, Word, Excel)
+
+### Page Layout Integration
+
+The Script Placeholders widget is part of the default layout for Report Configuration pages (`cf.cplace.officeReports.configuration`):
+
+**Standard Layout Structure**:
+```
+Row 1: [Headline Widget - Full Width]
+Row 2: [Settings Group - 6 cols] [Script Editor - 6 cols]
+Row 3: [Template Placeholders - 6 cols] [Script Placeholders - 6 cols]
+Row 4: [Files Widget - 6 cols]
+```
+
+**Layout Position**: Bottom-right section, displayed side-by-side with Template Placeholders widget
+
+### Plugin Ecosystem
+
+**Parent Plugin**: cplace Office Reports (`cf.cplace.officeReports`)
+
+**Plugin Purpose**: Enables creation of Office reports (PowerPoint, Word, Excel) using:
+- Office templates with placeholder syntax
+- Low-Code scripts to populate placeholders
+- Data from cplace pages and searches
+
+**Report Generation Flow**:
+1. User creates Report Configuration page
+2. Uploads Office template with placeholders (e.g., `{companyName}`)
+3. Writes Low-Code script to define placeholder values
+4. **Script Placeholders widget validates the script** ← This widget's role
+5. **Template Placeholders widget validates the template** ← Companion widget's role
+6. Report Generation widget generates final Office documents
+
+### Prerequisites
+
+To use this widget effectively:
+
+1. **Office Reports Plugin**: Must be installed and active
+2. **Report Configuration Page**: Must be of type `cf.cplace.officeReports.configuration`
+3. **Template**: An Office template (PowerPoint, Word, or Excel) should be uploaded
+4. **Script**: A Low-Code script should be written in the Script attribute
+5. **Template Placeholders Widget**: Must be present in the layout to provide template data
+
+### Dependencies
+
+**JavaScript Libraries**:
+- **esprima**: JavaScript parser for AST analysis
+- **AngularJS**: UI framework for table rendering and directives
+
+**Backend Dependencies**:
+- Script parsing and execution framework
+- Template parsing services (PowerPoint, Word, Excel)
+- Report generation utilities
+
+## Key Implementation Files
+
+**Backend (Java)**:
+- Widget Definition: `/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/ScriptPlaceholdersWidgetDefinition.java`
+- Placeholder Utilities: `/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/PlaceholderWidgetUtil.java`
+- Template Substitution: `/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/PlaceholderWidgetTemplateSubstitution.java`
+
+**Frontend (TypeScript/Angular)**:
+- Controller: `/cf.cplace.officeReports/assets/ts/controllers/ScriptPlaceholdersCtrl.ts`
+- Directive: `/cf.cplace.officeReports/assets/ts/directives/ScriptPlaceholdersDirective.ts`
+- Table Component: `/cf.cplace.officeReports/assets/ts/components/scriptPlaceholdersTable.ts`
+- Script Parser Service: `/cf.cplace.officeReports/assets/ts/services/ScriptParserService.ts`
+
+**Templates**:
+- Widget Template: `/cf.cplace.officeReports/src/main/resources/cf/cplace/officeReports/script/scriptPlaceholdersWidgetDefinition.htm`
+- Table Template: `/cf.cplace.officeReports/src/main/resources/cf/cplace/officeReports/script/widgetComponentTemplateFunctions/scriptPlaceholdersTable.htm`
+
+## Localization
+
+**Widget Name**:
+- English: "Script"
+- German: "Skript"
+
+**Table Headers**:
+- Line: `placeholder.table.line`
+- Placeholder: `placeholder.label`
+- Present in Template: `placeholder.presentInTemplate`
+
+**Tooltips**:
+- Present in template: `placeholder.presentInTemplateTooltip` - "The placeholder is present in the template"
+- Dynamic column: `placeholder.dynamicColumnTooltip` - "The placeholder is added dynamically in the script"
+
+## Summary
+
+The Script Placeholders widget is a specialized development and validation tool for Office report configurations. It automatically parses Low-Code scripts to extract placeholder definitions and validates them against Office templates, providing immediate feedback to report developers. The widget operates as part of a larger ecosystem within the Office Reports plugin, working in tandem with the Template Placeholders widget to ensure consistency between scripts and templates. Its primary value lies in preventing runtime errors, reducing development time, and serving as live documentation of report data requirements.