## Overview A frameless widget for displaying styled HTML content that integrates seamlessly with page design. The `content` attribute holds static HTML; to make content **dynamic**, embed `cf.cplace.lowCodeWidgets.lowCodeText` widgets that execute scripts and render output inline. **Use when**: Dynamic banners, custom breadcrumb navigation, KPI cards, conditional content display, or any content that should appear as native page content without a widget frame. **Alternative**: Rich String provides similar functionality but with a visible frame - better when users need to recognize the widget. ## Use Cases ### KPI Cards and Dashboard Numbers Preferred over Highcharts for simple number displays - provides full CSS control without chart library overhead. ```html
Active Suppliers
``` | Need | Widget Choice | |------|---------------| | Simple number/count display | **demoRichString** | | Bar/pie/line chart, gauge | scriptingHighcharts | ### Dynamic Page Banners Combine page title with status indicators in full-width banners using solution-specific CSS classes. Embed multiple Low-Code Text widgets for title (localized) and RAG status indicators that render conditionally. ### Custom Breadcrumb Navigation Generate domain-specific breadcrumb trails when standard cplace navigation is insufficient. Use cplace CSS classes (`cf-cplace-breadcrumbs-wrapper`) and PJAX links (`cplace-pjax-link`) for native appearance and smooth navigation. ### Conditional Content Display Content that changes based on page attributes or user context. Scripts return empty strings when conditions aren't met, leaving no trace. Supports language detection via `cplace.currentUser.getLanguage()`. ## Embedded Widget Pattern (Widget-in-Widget) The Rich Text widget acts as a **styled container**, while embedded Low-Code Text widgets (`cf.cplace.lowCodeWidgets.lowCodeText`) provide **dynamic content**. ### Architecture ``` +-------------------------------------------------------------+ | Rich Text Widget (demoRichString) | | +----------------------------------------------------------+ | | | | +----------------------------------------------------------+ +-------------------------------------------------------------+ ``` ### How It Works 1. **Container Definition**: The Rich Text widget holds HTML markup with CSS classes for styling 2. **Embedding Points**: Special widget tags mark where dynamic content should appear 3. **Widget Configuration**: Each embedded widget is stored as base64-encoded JSON 4. **Independent Execution**: Each embedded widget runs its script independently 5. **Inline Rendering**: Output replaces the widget tag in the final HTML ### Embedded Widget Configuration Each embedded Low-Code Text widget has these key properties: | Property | Purpose | |----------|---------| | `dataSource` | How the widget gets page context (`search` or direct reference) | | `includeAllSearchResults` | Whether to iterate over multiple pages | | `tableSelectionOnly` | Restrict to table selections | | `script` | The cplaceJS code that generates HTML output | ### Script Context: `embeddingPage` **Critical**: Scripts inside embedded widgets access the current page through `embeddingPage`, not `currentPage`. ```javascript // Correct - use embeddingPage const pageName = embeddingPage.getName(); const status = embeddingPage.get('cf.cplace.status'); // Wrong - currentPage is undefined in embedded context const pageName = currentPage.getName(); // Will fail! ``` ### Script Patterns **Pattern 1: Localized Title Display** ```javascript const lang = cplace.currentUser.getLanguage(); const label = lang === 'de' ? 'Planseite' : 'Schedule Page'; return '' + label + ': ' + embeddingPage.getName() + ''; ``` **Pattern 2: Conditional Status Indicator** ```javascript const status = embeddingPage.get('cf.cplace.ratingLight'); if (!status) return ''; // Nothing displayed when no status const colors = { 'gruen': 'green', 'gelb': 'yellow', 'rot': 'red' }; const color = colors[status] || 'gray'; return ''; ``` **Pattern 3: Hierarchical Navigation** ```javascript const folder = embeddingPage.get('cf.cplace.rmProjectFolder') ?? embeddingPage.getParent()?.get('cf.cplace.rmProjectFolder'); const parent = embeddingPage.getParent(); let html = ''; return html; ``` **Pattern 4: Multi-Language Content** ```javascript const lang = cplace.currentUser.getLanguage(); const messages = { 'en': { welcome: 'Welcome', description: 'This is your project dashboard.' }, 'de': { welcome: 'Willkommen', description: 'Dies ist Ihr Projekt-Dashboard.' } }; const msg = messages[lang] || messages['en']; return '

' + msg.welcome + '

' + msg.description + '

'; ``` ### Best Practices **Return Empty Strings, Not Null** ```javascript // Good - clean output when condition not met if (!shouldShow) return ''; // Bad - may cause rendering issues if (!shouldShow) return null; if (!shouldShow) return undefined; ``` **Use Null-Safe Navigation** ```javascript // Good - handles missing attributes gracefully const folder = embeddingPage.get('cf.cplace.folder'); const folderName = folder?.getName() ?? 'Unknown'; // Bad - will throw error if folder is null const folderName = embeddingPage.get('cf.cplace.folder').getName(); ``` **Keep Scripts Focused** Each embedded widget should do one thing well. For complex displays, use multiple embedded widgets rather than one monolithic script. ### Common Embedded Widget Configurations | Use Case | Data Source | Script Focus | |----------|-------------|--------------| | Page Title Display | Direct/Search | `embeddingPage.getName()` with labels | | Attribute Values | Direct/Search | Read and format specific attributes | | Status Indicators | Direct/Search | Conditional rendering based on status | | Navigation Links | Search | Traverse hierarchy, generate link HTML | | Localized Messages | Direct | Language detection, message lookup | | KPI Counts | Search | Query pages, return formatted count | ## Design Considerations **Trade-offs**: - Frameless design provides visual flexibility but users cannot identify content as widget-generated - Embedded widgets add power but complexity - base64 encoding requires tooling support - Custom CSS classes must exist in workspace/solution stylesheets **When NOT to Use**: Users need inline editing (use Rich String), content should be identifiable as widget, simple page title (use Page View Headline), or standard navigation suffices. **Typical Positioning**: Row 0, full width (12 cols) for banners and navigation. Common layout pairs with `layoutTabsWidget` in Row 1. ## Related Widgets | Widget | Relationship | |--------|-------------| | Rich String | Visible frame; better for user-editable content | | Page View Headline | Simpler alternative for just page title | | Low-Code Text | Embedded within this widget for dynamic content | | Layout Tabs Widget | Commonly paired in Row 1 below the header |