## Overview

Represents a dynamically generated code block with content defined using cplaceJS. The widget displays formatted code snippets with syntax highlighting, where the code content is generated dynamically through a cplaceJS script. This widget is useful for showing code examples, configuration snippets, or any text content that benefits from code formatting, with the content determined at runtime based on page data or other dynamic criteria.

> **Text-only rendering**: This widget renders content as **plain text** inside `<pre><code>` using `ng-bind` (equivalent to `textContent`). It does **not** render HTML. Any HTML tags in the script return value are displayed as literal text, not rendered. For scripted HTML output (KPI cards, pivot tables, dynamic banners, formatted content), use the **Low-Code Text** widget (`cf.cplace.lowCodeWidgets.lowCodeText`) embedded inside a **Rich String** or **Text without Widget Frame** container.

**Use when you need to:**
- Display code examples or snippets that change based on page context
- Show dynamically generated configuration files or scripts
- Present formatted text output from calculations or data transformations
- Create documentation pages with context-aware code samples

**Alternatives:**
- **Rich Text Widget** - For static code blocks or when content doesn't need to be generated dynamically
- **Low-Code Text Widget** (`cf.cplace.lowCodeWidgets.lowCodeText`) - For scripted HTML output rendered inline within a rich string container

## Operating Modes

### Dynamic Content Generation

The widget's primary mode is to execute a cplaceJS expression that returns the code content to display. The script has access to the embedding page's context and can:
- Extract attribute values and format them as code
- Generate configuration snippets based on page properties
- Construct code examples using template patterns
- Transform data into formatted output

**Typical scenarios:**
- Showing API request examples with actual parameter values from the page
- Displaying generated SQL queries based on filter selections
- Presenting configuration snippets with environment-specific values
- Creating documentation with examples that reflect current settings

## Design Considerations

### When to Use This Widget

Use the Dynamic Code Block when:
- The code content needs to be generated based on page data
- You want syntax highlighting for better readability
- The content should update when page attributes change
- You need to show technical content (JSON, XML, code) in a formatted way

Avoid when:
- The code content is static and doesn't change (use Rich Text instead)
- You need rendered HTML output such as KPI cards, formatted tables, or styled content (use Low-Code Text embedded in a Rich String instead)
- You need user interaction with the code (editing, copying with click)
- The output is better suited to table or structured display
- Performance is critical and the script is computationally expensive

### Content Formatting

The widget provides code block formatting with monospace font and syntax highlighting, making it ideal for technical content. Consider:
- The readability of the generated content
- Whether line numbers or specific syntax highlighting is needed
- The length of the generated code (very long blocks may need scrolling)
- How the code block integrates with surrounding widgets

### Script Performance

Since the cplaceJS expression executes on page load and potentially on updates:
- Keep scripts lightweight and efficient
- Avoid complex computations that could slow page rendering
- Cache results when possible if the same code is generated repeatedly
- Consider whether the dynamic generation is necessary or if static content would suffice

## Common Pitfalls

- **Complex script logic** - Overly complicated scripts make maintenance difficult; consider simplifying or using helper functions
- **Missing error handling** - Scripts that fail silently leave the widget empty; include fallback content
- **Excessive content** - Very long code blocks can overwhelm the page; consider pagination or showing excerpts
- **Lack of context** - Without explanatory text nearby, users may not understand what the code represents

## Related Patterns

- **Documentation Generation** - Automatically creating code examples based on actual system configuration
- **Configuration Display** - Showing current settings in a copy-pasteable format
- **Query Builder Output** - Displaying the generated query that will be executed based on user selections
- **API Documentation** - Creating endpoint examples with real parameter values from related pages