Editor Widget Documentation

Overview​

The Editor widget provides a powerful rich text editing interface for creating and editing formatted content. It's built on CKEditor's DecoupledEditor and offers a comprehensive set of formatting tools and customization options.

Basic Configuration​

Widget Properties​

Name​

• Field: Name
• Description: Display name for the widget
• Type: Text input
• Usage: Used for identification and can be referenced in validation messages

Variable/Model​

• Field: Variable/Model
• Description: The data model property that will store the editor content
• Type: Text input
• Required: Yes
• Usage: Defines the variable name used to store and retrieve the editor's HTML content

Default Content​

Default Value​

• Field: Default Value
• Description: Initial HTML content displayed in the editor
• Configuration: Click "Edit" button to open the HTML editor
• Features:
  • Rich text formatting
  • HTML source editing
  • Live preview
  • Supports dynamic content with template variables

Editor Features​

Toolbar Configuration​

The editor includes a comprehensive toolbar with the following tools:

Text Formatting​

• Headings: H1 through H6 heading styles
• Font Family: Change font typeface
• Font Size: Adjust text size
• Text Alignment: Left, center, right, justify
• Font Color: Change text color
• Background Color: Highlight text with background colors

Text Styling​

• Bold: Make text bold
• Italic: Italicize text
• Strikethrough: Strike through text
• Underline: Underline text

Lists and Structure​

• Bulleted Lists: Create unordered lists
• Numbered Lists: Create ordered lists
• Outdent/Indent: Adjust list and paragraph indentation
• Block Quotes: Format text as quotations

Advanced Features​

• Links: Insert and edit hyperlinks
• Tables: Insert and format tables
• Undo/Redo: Navigate edit history

Content Management​

Placeholder Text​

• Field: Placeholder (under Style section)
• Description: Text displayed when editor is empty
• Usage: Provides guidance to users about expected content

HTML Content Access​

• Data Binding: Content is automatically saved to the specified model variable
• Format: Stored as HTML markup
• Real-time Updates: Content updates trigger change events

Validation and Rules​

Field Validation​

Required Field​

• Configuration: Set in Validation section
• Per Screen: Can be configured differently for each screen/device type
• Advanced Conditions: Support for conditional requirements using JavaScript expressions

Custom Validation Rules​

• Location: Rules section in widget configuration
• Types Available:
  • Length validation (minimum/maximum characters)
  • Pattern matching (regular expressions)
  • Custom JavaScript validation functions
• Error Messages: Customizable validation failure messages

Screen-Based Validation​

Visibility Control​

• Available: Whether widget appears on specific screens
• Visible: Dynamic visibility based on conditions
• Required: Whether field is mandatory on each screen
• Disabled: Whether field is read-only on specific screens

Advanced Conditions​

• JavaScript Expressions: Use template variables in conditions
• Dynamic Evaluation: Conditions re-evaluated when dependent variables change
• Multi-screen Support: Different rules for mobile, tablet, desktop

Styling and Layout​

Appearance Options​

Dimensions​

• Width: Custom width specification (CSS units)
• Height: Custom height specification (CSS units)
• Layout: Block or inline display mode
• Border: Toggle border display

CSS Customization​

• Class Names: Add custom CSS classes
• Dynamic Classes: Conditional class application based on data
• Theme Integration: Inherits from global interface styling

Responsive Design​

• Screen Adaptation: Automatically adjusts to different screen sizes
• Touch Support: Optimized for touch interactions on mobile devices
• Toolbar Responsiveness: Toolbar adapts to available space

Interactive Features​

Event Handling​

On Click Action​

• Configuration: Set in Global section
• JavaScript Support: Write custom JavaScript functions
• Variable Access: Access widget value through SF_input variable
• Integration: Connect with other widgets and system functions

Change Detection​

• Real-time Updates: Content changes immediately update the model
• Event Triggering: Can trigger other widget updates or actions
• Form Integration: Participates in form validation and submission

Read-Only Mode​

• Automatic: Enabled when widget is disabled
• Conditional: Can be set based on user permissions or data state
• Visual Feedback: Clear indication when editing is not available

Advanced Configuration​

Data Integration​

Template Variables​

• Syntax: Use ${} notation for dynamic content
• Model Access: Reference other form data in default content
• Global Variables: Access system-wide variables and settings

Form Integration​

• Validation Participation: Integrates with form-wide validation
• Submission Handling: Content included in form data submission
• Reset Capabilities: Can be cleared or reset to default values

Accessibility Features​

Keyboard Navigation​

• Full Support: Complete keyboard accessibility
• Tab Order: Proper tabbing sequence
• Shortcuts: Standard editing keyboard shortcuts

Screen Reader Support​

• ARIA Labels: Proper labeling for assistive technologies
• Semantic HTML: Generated content maintains semantic structure
• Focus Management: Clear focus indicators and management

Usage Examples​

Basic Rich Text Editor​

// Configuration
{
  name: "Article Content",
  model: "articleContent",
  options: {
    placeholder: "Enter your article content here...",
    html: "<p>Start writing your article...</p>"
  }
}

Blog Post Editor with Validation​

// Configuration with validation
{
  name: "Blog Post",
  model: "blogPost",
  options: {
    placeholder: "Write your blog post...",
    rules: [
      {
        rule: "minLength",
        value: 100,
        message: "Blog post must be at least 100 characters"
      }
    ]
  },
  validation: {
    mobile: { required: true, visible: true },
    desktop: { required: true, visible: true }
  }
}

Dynamic Content Editor​

// Editor with dynamic default content
{
  name: "Email Template",
  model: "emailContent", 
  options: {
    html: "<p>Dear ${customerName},</p><p>Thank you for your order...</p>",
    placeholder: "Customize your email template..."
  }
}

Conditional Editor​

// Editor that appears conditionally
{
  name: "Additional Comments",
  model: "comments",
  options: {
    placeholder: "Add any additional comments..."
  },
  validation: {
    mobile: { 
      visible: "{{requiresComments}} === true",
      required: "{{requiresComments}} === true"
    }
  }
}

Best Practices​

Content Management​

1. Structure Content: Use headings and lists for better organization
2. Consistent Formatting: Maintain consistent styling throughout content
3. Link Management: Ensure all links are valid and properly formatted
4. Image Optimization: Keep images appropriately sized for web use

User Experience​

1. Clear Placeholders: Provide helpful placeholder text
2. Appropriate Sizing: Size editor appropriately for expected content
3. Validation Feedback: Provide clear validation messages
4. Save Indicators: Consider adding save status indicators for long content

Performance​

1. Content Length: Be mindful of very long content and performance impact
2. Image Handling: Optimize images before inserting
3. Clean HTML: Regularly clean up unnecessary HTML formatting
4. Mobile Optimization: Test editor performance on mobile devices

Troubleshooting​

Common Issues​

Editor Not Loading​

• Verify CKEditor scripts are properly loaded
• Check for JavaScript errors in browser console
• Ensure proper widget configuration

Content Not Saving​

• Verify model variable name is correct and unique
• Check form submission handling
• Ensure proper change event binding

Formatting Issues​

• Check for conflicting CSS styles
• Verify HTML content is properly structured
• Test across different browsers and devices

Validation Problems​

• Verify validation rules syntax
• Check conditional expressions for errors
• Ensure required fields are properly marked

Performance Optimization​

• Limit toolbar options if not needed
• Consider lazy loading for multiple editors
• Optimize default content size
• Regular cleanup of generated HTML

Integration Notes​

Form Integration​

• Participates in form validation cycle
• Content included in form submission data
• Supports form reset and clear operations

API Integration​

• Content can be sent to backend APIs
• Supports real-time collaboration features
• Can integrate with content management systems

Security Considerations​

• HTML content should be sanitized on backend
• Consider XSS protection for user-generated content
• Validate content length and structure server-side