Package Exports

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

Readme

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: 'john@example.com',
          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

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

License

MIT License - see LICENSE file for details.