Text Template Management Module

A comprehensive template management system for DBS Portal with Handlebars-based template engine, variable management, live preview, version control, and localization support.

Features

🎨 Template Engine

• Handlebars Integration: Powerful template engine with custom helpers
• Variable System: Type-safe variable definitions with validation
• Live Preview: Real-time template rendering with sample data
• Syntax Validation: Comprehensive template validation and error reporting

📝 Rich Editor Experience

• Monaco Editor: VS Code-like editing experience with syntax highlighting
• Auto-completion: Intelligent variable and helper suggestions
• Error Detection: Real-time syntax and logic error detection
• Helper Integration: Easy insertion of template helpers and functions

🔧 Variable Management

• Type System: Support for string, number, boolean, date, email, URL, phone, currency, array, and object types
• Validation Rules: Pattern matching, min/max values, length constraints, and option lists
• Grouping: Organize variables into logical groups for better management
• Default Values: Set default and example values for variables

🌍 Localization Support

• Multi-language: Template localization for different languages and regions
• Locale-specific: Date, number, and currency formatting per locale
• Translation Management: Track translation progress and completeness

📊 Version Control

• Template Versions: Maintain multiple versions of templates
• Change Tracking: Detailed changelog and version history
• Active Version: Control which version is currently active
• Rollback Support: Easy rollback to previous versions

📈 Analytics & Statistics

• Usage Tracking: Monitor template usage and performance
• Render Analytics: Track rendering times and error rates
• Popular Variables: Identify most-used variables and patterns
• Global Analytics: System-wide template statistics

Installation

npm install @dbs-portal/module-text-template-management

Dependencies

Required

• @tanstack/react-query - Data fetching and caching
• antd - UI components
• react - React framework

Optional (Enhanced Features)

• handlebars - Template engine (fallback available)
• monaco-editor - Rich code editor (textarea fallback)
• react-monaco-editor - React wrapper for Monaco
• marked - Markdown support
• dompurify - HTML sanitization

Quick Start

1. Basic Template Management

import { TemplateList, TemplateEditor } from '@dbs-portal/module-text-template-management'

function TemplateManagementPage() {
  const [selectedTemplate, setSelectedTemplate] = useState(null)

  return (
    <div>
      <TemplateList 
        onTemplateSelect={setSelectedTemplate}
        showActions
        selectable
      />
      
      {selectedTemplate && (
        <TemplateEditor
          template={selectedTemplate}
          showPreview
          onChange={(content) => console.log('Content changed:', content)}
        />
      )}
    </div>
  )
}

2. Template Editor with Preview

import { TemplateEditor, TemplatePreview } from '@dbs-portal/module-text-template-management'

function TemplateEditorPage() {
  const [content, setContent] = useState('Hello {{name}}!')
  const [variables, setVariables] = useState([
    {
      name: 'name',
      displayName: 'Name',
      type: 'string',
      required: true,
      defaultValue: 'World'
    }
  ])

  return (
    <Row gutter={16}>
      <Col span={12}>
        <TemplateEditor
          content={content}
          variables={variables}
          onChange={setContent}
          onVariableChange={setVariables}
        />
      </Col>
      <Col span={12}>
        <TemplatePreview
          content={content}
          variables={{ name: 'John Doe' }}
        />
      </Col>
    </Row>
  )
}

3. Variable Management

import { TemplateVariableManager } from '@dbs-portal/module-text-template-management'

function VariableManagerPage() {
  const [variables, setVariables] = useState([])
  const [groups, setGroups] = useState([])

  return (
    <TemplateVariableManager
      variables={variables}
      groups={groups}
      onChange={setVariables}
      onGroupChange={setGroups}
    />
  )
}

4. Template Rendering

import { useRenderTemplate } from '@dbs-portal/module-text-template-management'

function RenderExample() {
  const renderMutation = useRenderTemplate()

  const handleRender = async () => {
    try {
      const result = await renderMutation.mutateAsync({
        templateId: 'template-123',
        variables: {
          name: 'John Doe',
          email: '[email protected]',
          date: new Date()
        },
        options: {
          locale: 'en-US',
          escapeHtml: true
        }
      })
      
      console.log('Rendered content:', result.content)
    } catch (error) {
      console.error('Rendering failed:', error)
    }
  }

  return (
    <Button onClick={handleRender} loading={renderMutation.isPending}>
      Render Template
    </Button>
  )
}

API Reference

Components

TemplateList

Comprehensive template management interface with filtering and bulk operations.

interface TemplateListProps {
  filters?: Partial<TemplateSearchFilters>
  onTemplateSelect?: (template: Template) => void
  onTemplateEdit?: (template: Template) => void
  onTemplateDelete?: (template: Template) => void
  onTemplateClone?: (template: Template) => void
  showActions?: boolean
  selectable?: boolean
  className?: string
}

TemplateEditor

Rich template editor with Monaco integration and live validation.

interface TemplateEditorProps {
  template?: Template
  content?: string
  variables?: TemplateVariable[]
  engine?: TemplateEngine
  onChange?: (content: string) => void
  onVariableChange?: (variables: TemplateVariable[]) => void
  readOnly?: boolean
  showPreview?: boolean
  className?: string
}

TemplatePreview

Live template preview with variable editing capabilities.

interface TemplatePreviewProps {
  template?: Template
  content?: string
  variables?: Record<string, any>
  engine?: TemplateEngine
  locale?: string
  onVariableChange?: (variables: Record<string, any>) => void
  className?: string
}

TemplateVariableManager

Advanced variable and group management interface.

interface TemplateVariableManagerProps {
  variables: TemplateVariable[]
  groups?: TemplateVariableGroup[]
  onChange?: (variables: TemplateVariable[]) => void
  onGroupChange?: (groups: TemplateVariableGroup[]) => void
  readOnly?: boolean
  className?: string
}

Hooks

Template CRUD Operations

• useTemplates(page, pageSize, filters) - Fetch paginated templates
• useTemplate(id) - Fetch single template
• useCreateTemplate() - Create new template
• useUpdateTemplate() - Update existing template
• useDeleteTemplate() - Delete template
• useCloneTemplate() - Clone template

Template Operations

• useValidateTemplate() - Validate template syntax
• usePreviewTemplate() - Preview template with sample data
• useTestTemplate() - Test template with real data
• useRenderTemplate() - Render template with variables

Version Management

• useTemplateVersions(id) - Get template versions
• useCreateTemplateVersion() - Create new version
• useSetActiveTemplateVersion() - Set active version

Localization

• useTemplateLocalizations(id) - Get localizations
• useUpdateTemplateLocalization() - Update localization
• useDeleteTemplateLocalization() - Delete localization

Analytics

• useTemplateStatistics(id) - Get template statistics
• useTemplateAnalytics(id, period) - Get usage analytics
• useGlobalTemplateAnalytics() - Get global analytics

Template Engine

Built-in Helpers

<!-- Date formatting -->
{{formatDate createdAt "short"}}
{{formatDate updatedAt "time"}}

<!-- Number formatting -->
{{formatNumber price}}
{{formatCurrency amount "USD"}}

<!-- String manipulation -->
{{uppercase name}}
{{lowercase email}}
{{capitalize title}}
{{truncate description 100}}

<!-- Conditionals -->
{{#if (eq status "active")}}Active{{/if}}
{{#unless (gt count 0)}}No items{{/unless}}

<!-- Arrays -->
{{#each items}}
  {{@index}}: {{this.name}}
{{/each}}
{{join tags ", "}}

<!-- Markdown -->
{{markdown content}}

<!-- Default values -->
{{default name "Anonymous"}}

Variable Types

type TemplateVariableType = 
  | 'string'    // Text input
  | 'number'    // Numeric input
  | 'boolean'   // Switch/checkbox
  | 'date'      // Date picker
  | 'email'     // Email input with validation
  | 'url'       // URL input with validation
  | 'phone'     // Phone number input
  | 'currency'  // Currency input with formatting
  | 'array'     // Multi-select/tags
  | 'object'    // JSON object input

Advanced Usage

Custom Template Engine

import { createTemplateEngine } from '@dbs-portal/module-text-template-management'

const customEngine = createTemplateEngine({
  allowUnsafeContent: false,
  enableMarkdown: true,
  maxRenderTime: 10000,
  currencyCode: 'EUR'
})

const result = await customEngine.render(template, {
  variables: data,
  locale: 'de-DE',
  escapeHtml: true
})

Template Validation

import { templateEngine } from '@dbs-portal/module-text-template-management'

const validation = templateEngine.validate(content, variables)

if (!validation.isValid) {
  console.log('Errors:', validation.errors)
  console.log('Missing variables:', validation.missingVariables)
  console.log('Unused variables:', validation.unusedVariables)
}

Bulk Operations

import { useBulkUpdateTemplates, useBulkDeleteTemplates } from '@dbs-portal/module-text-template-management'

const bulkUpdate = useBulkUpdateTemplates()
const bulkDelete = useBulkDeleteTemplates()

// Update multiple templates
await bulkUpdate.mutateAsync({
  templateIds: ['id1', 'id2', 'id3'],
  updates: { status: 'active', category: 'email' }
})

// Delete multiple templates
await bulkDelete.mutateAsync(['id1', 'id2', 'id3'])

More example: Examples

Configuration

Environment Variables

# Template engine settings
VITE_TEMPLATE_MAX_RENDER_TIME=5000
VITE_TEMPLATE_MAX_CONTENT_LENGTH=1000000
VITE_TEMPLATE_ALLOW_UNSAFE_CONTENT=false

# Editor settings
VITE_TEMPLATE_EDITOR_THEME=vs-light
VITE_TEMPLATE_ENABLE_MONACO=true
VITE_TEMPLATE_ENABLE_MARKDOWN=true

Development

Building

npm run build

Testing

npm test

Type Checking

npm run type-check

Contributing

1. Follow established patterns for components, hooks, and services
2. Ensure all new features have TypeScript types
3. Add comprehensive validation for template operations
4. Update documentation for API changes
5. Test with various template scenarios

License

MIT License - see LICENSE file for details.