Skip to main content

HTML Widget Documentation

Overview

The HTML widget allows you to embed custom HTML content directly into your interface. This widget provides complete flexibility for displaying rich content, custom layouts, or integrating third-party HTML components while maintaining full control over styling and behavior.

Basic Configuration

Global Settings

Name

  • Field: Widget name identifier
  • Usage: Set a descriptive name for easy identification in the widget tree
  • Example: "Custom Header", "Product Description"

Variable/Model

  • Field: Model binding for the widget
  • Usage: Bind the widget to a data model or variable for dynamic content
  • Format: Use dot notation for nested properties (e.g., user.profile.bio)
  • Validation: The system validates model names and shows warnings for potential issues

Content Configuration

HTML Content Editor

Edit HTML Button

  • Location: Global section → Edit HTML
  • Function: Opens a code editor for writing custom HTML content
  • Features:
    • Syntax highlighting
    • Code completion
    • Error detection
    • Preview capabilities

Supported HTML

  • Standard HTML5 elements and attributes
  • Inline CSS styling
  • JavaScript integration (with platform security considerations)
  • Dynamic content using template variables

Template Variables

Access dynamic data within your HTML content:

<!-- Access model data -->
<div>{{model.fieldName}}</div>

<!-- Use global variables -->
<span>{{globalVariable}}</span>

<!-- Platform-specific variables -->
<p>User: {{user.name}}</p>

Validation Configuration

Screen-Based Validation

Configure widget behavior across different screens/contexts:

Available

  • Purpose: Controls whether the widget exists in the DOM
  • Options:
    • Boolean toggle (true/false)
    • Advanced condition using JavaScript expressions

Visible

  • Purpose: Controls widget visibility (display/hide)
  • Options:
    • Boolean toggle
    • Advanced condition with template variables
  • Advanced Example: {{user.role}} === 'admin'

Required

  • Purpose: Makes the widget mandatory for form validation
  • Note: Primarily used when HTML widget contains form elements
  • Options: Boolean or conditional expression

Disable

  • Purpose: Disables interactive elements within the widget
  • Options: Boolean or conditional expression

Advanced Validation Conditions

Condition Syntax

  • Use {{variableName}} to access model data
  • Support for JavaScript expressions
  • Comparison operators: ===, !==, >, <, >=, <=
  • Logical operators: &&, ||, !

Examples

// Show only for admin users
{{user.role}} === 'admin'

// Hide when form is submitted
{{form.status}} !== 'submitted'

// Show based on multiple conditions
{{user.isActive}} && {{user.permissions.includes('view_content')}}

Style Configuration

CSS Classes

Static Classes

  • Field: Class names
  • Usage: Apply predefined CSS classes
  • Format: Space-separated class names
  • Example: btn btn-primary custom-style

Dynamic Classes

  • Field: Dynamic classes button
  • Usage: Apply classes based on conditions
  • Format: JavaScript object notation
  • Example:
{
'active': {{isActive}},
'highlighted': {{priority}} > 5,
'error': {{hasError}}
}

Responsive Design

The widget inherits responsive capabilities from the parent grid system:

  • Automatic responsive behavior
  • CSS Grid and Flexbox support
  • Mobile-first approach

Rules and Validation

Custom Validation Rules

Add client-side validation rules for interactive HTML content:

Rule Types

  • Pattern: Regular expression validation
  • Length: Minimum/maximum character limits
  • Range: Numeric range validation
  • Custom: JavaScript function validation

Rule Configuration

  1. Click "Add rule" button
  2. Select rule type from dropdown
  3. Enter validation value/pattern
  4. Provide error message
  5. Configure rule priority

Example Rules

// Email validation
Rule: Pattern
Value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
Message: "Please enter a valid email address"

// Required field
Rule: Required
Value: true
Message: "This field is required"

Widget Template Structure

Generated Component

The widget generates a Vue.js component with:

  • Unique component ID
  • Reactive data binding
  • Conditional rendering
  • Event handling capabilities

DOM Structure

<div id="[widgetId]" 
v-if="[visibilityCondition]"
class="[staticClasses]"
:class="[dynamicClasses]">
<!-- Your custom HTML content -->
</div>

Integration Examples

Basic HTML Content

<div class="custom-section">
<h2>Welcome {{user.firstName}}</h2>
<p>Last login: {{user.lastLogin | formatDate}}</p>
</div>

Interactive Elements

<div class="interactive-widget">
<button onclick="customFunction()" class="btn btn-primary">
Click Me
</button>
<input type="text" v-model="inputValue" placeholder="Enter text">
</div>

Conditional Content

<div v-if="{{user.isAdmin}}">
<h3>Admin Panel</h3>
<div class="admin-controls">
<!-- Admin-specific content -->
</div>
</div>

Best Practices

Security Considerations

  • Sanitize user-generated content
  • Avoid inline JavaScript in production
  • Use platform-provided security features
  • Validate all dynamic data

Performance Optimization

  • Minimize DOM complexity
  • Use efficient CSS selectors
  • Implement lazy loading for heavy content
  • Optimize images and media

Accessibility

  • Include proper ARIA attributes
  • Ensure keyboard navigation support
  • Provide alternative text for images
  • Maintain proper heading hierarchy

Maintainability

  • Use semantic HTML structure
  • Comment complex functionality
  • Follow consistent naming conventions
  • Separate concerns (structure, style, behavior)

Troubleshooting

Common Issues

Widget Not Displaying

  • Check visibility conditions
  • Verify model bindings
  • Ensure proper HTML syntax
  • Review browser console for errors

Styling Problems

  • Verify CSS class names
  • Check for conflicting styles
  • Ensure responsive design compatibility
  • Test across different screen sizes

Dynamic Content Not Updating

  • Confirm model binding syntax
  • Check for reactivity issues
  • Verify data source connections
  • Review JavaScript console errors

Debug Mode

Enable debug mode to:

  • View generated component structure
  • Monitor data binding updates
  • Track validation rule execution
  • Inspect DOM changes

Advanced Features

Custom Event Handling

Implement custom JavaScript functions within your HTML:

<div onclick="handleClick(event)" data-custom="{{modelData}}">
Interactive Element
</div>

Third-Party Integration

Embed external libraries and components:

<div id="chart-container">
<!-- Chart.js, D3.js, or other library integration -->
</div>
<script>
// Initialize third-party component
initializeChart({{chartData}});
</script>

Form Integration

Include form elements that integrate with the platform's form system:

<div class="form-section">
<label for="customField">Custom Input:</label>
<input type="text"
id="customField"
name="customField"
v-model="{{model.customField}}"
required>
</div>

This HTML widget provides maximum flexibility while maintaining integration with the platform's validation, styling, and data binding systems. Use it when standard widgets don't meet your specific requirements or when you need complete control over the presentation layer.