Class: Uniword::Template::Template

Inherits:
Object
  • Object
show all
Defined in:
lib/uniword/template/template.rb

Overview

Main template class for Word document templates.

Represents a Word document with embedded Uniword template syntax in comments. Coordinates parsing and rendering to produce filled documents from data.

Workflow:

  1. Load template from .docx file

  2. Extract markers from comments (via TemplateParser)

  3. Render with data (via TemplateRenderer)

  4. Save filled document

Examples:

Load and render template

template = Template.load('report_template.docx')
data = { title: "Annual Report", sections: [...] }
document = template.render(data)
document.save('filled_report.docx')

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ Template

Initialize template with document

Parameters:

  • document (Document) —

    Template document



42
43
44
45
 
# File 'lib/uniword/template/template.rb', line 42

def initialize(document)
  @document = document
  @markers = extract_markers
end

Instance Attribute Details

#document ⇒ Document (readonly)

Template document

Returns:

  • (Document) —

    the current value of document



27
28
29
 
# File 'lib/uniword/template/template.rb', line 27

def document
  @document
end

#markers ⇒ Array<TemplateMarker> (readonly)

Extracted template markers

Returns:



27
28
29
 
# File 'lib/uniword/template/template.rb', line 27

def markers
  @markers
end

Class Method Details

.load(template_path) ⇒ Template

Load template from .docx file

Parameters:

  • template_path (String) —

    Path to template file

Returns:



34
35
36
37
 
# File 'lib/uniword/template/template.rb', line 34

def self.load(template_path)
  doc = Uniword::DocumentFactory.from_file(template_path)
  new(doc)
end

Instance Method Details

#conditionals ⇒ Array<TemplateMarker>

Get all conditional markers

Returns:



103
104
105
 
# File 'lib/uniword/template/template.rb', line 103

def conditionals
  @markers.select(&:conditional_start?)
end

#inspect ⇒ String

Inspect template for debugging

Returns:

  • (String) —

    Readable representation



132
133
134
135
136
 
# File 'lib/uniword/template/template.rb', line 132

def inspect
  "#<Uniword::Template markers=#{@markers.count} " \
    "variables=#{variables.count} " \
    "loops=#{loops.count}>"
end

#loops ⇒ Array<Hash>

Get all loop markers

Returns:

  • (Array<Hash>) —

    Loop information



93
94
95
96
97
98
 
# File 'lib/uniword/template/template.rb', line 93

def loops
  loop_starts = @markers.select(&:loop_start?)
  loop_starts.map do |m|
    { collection: m.collection, position: m.position }
  end
end

#preview ⇒ Hash

Preview template structure

Returns information about markers for debugging and validation.

Returns:

  • (Hash) —

    Template structure info



74
75
76
77
78
79
80
81
 
# File 'lib/uniword/template/template.rb', line 74

def preview
  {
    markers: @markers.count,
    variables: variables,
    loops: loops,
    conditionals: conditionals.count,
  }
end

#render(data, context: {}) ⇒ Document

Render template with data

Creates a new document by filling the template with provided data. Supports both Hash and custom object data sources.

Examples:

Render with hash

doc = template.render(title: "My Document")

Render with custom object

doc = template.render(my_model_object)

Render with context

doc = template.render(data, context: { author: "John" })

Parameters:

  • data (Hash, Object) —

    Data to fill template

  • context (Hash) (defaults to: {}) —

    Additional context variables

Returns:

  • (Document) —

    Rendered document



64
65
66
67
 
# File 'lib/uniword/template/template.rb', line 64

def render(data, context: {})
  renderer = TemplateRenderer.new(self, data, context)
  renderer.render
end

#template? ⇒ Boolean

Check if document is a template

Returns:

  • (Boolean) —

    true if contains markers



110
111
112
 
# File 'lib/uniword/template/template.rb', line 110

def template?
  @markers.any?
end

#valid? ⇒ Boolean

Check if template is valid

Returns:

  • (Boolean) —

    true if valid



125
126
127
 
# File 'lib/uniword/template/template.rb', line 125

def valid?
  validate.empty?
end

#validate ⇒ Array<String>

Validate template structure

Returns:

  • (Array<String>) —

    Validation errors (empty if valid)



117
118
119
120
 
# File 'lib/uniword/template/template.rb', line 117

def validate
  validator = TemplateValidator.new(self)
  validator.validate
end

#variables ⇒ Array<String>

Get all variable markers

Returns:

  • (Array<String>) —

    Variable names



86
87
88
 
# File 'lib/uniword/template/template.rb', line 86

def variables
  @markers.select(&:variable?).map(&:expression)
end