Module: Uniword::Builder

Defined in:
lib/uniword/builder.rb,
lib/uniword/builder/run_utils.rb,
lib/uniword/builder/has_borders.rb,
lib/uniword/builder/has_shading.rb,
lib/uniword/builder/run_builder.rb,
lib/uniword/builder/sdt_builder.rb,
lib/uniword/builder/toc_builder.rb,
lib/uniword/builder/base_builder.rb,
lib/uniword/builder/list_builder.rb,
lib/uniword/builder/chart_builder.rb,
lib/uniword/builder/image_builder.rb,
lib/uniword/builder/style_builder.rb,
lib/uniword/builder/table_builder.rb,
lib/uniword/builder/theme_builder.rb,
lib/uniword/builder/comment_builder.rb,
lib/uniword/builder/section_builder.rb,
lib/uniword/builder/deterministic_id.rb,
lib/uniword/builder/document_builder.rb,
lib/uniword/builder/footnote_builder.rb,
lib/uniword/builder/numbering_builder.rb,
lib/uniword/builder/paragraph_builder.rb,
lib/uniword/builder/table_row_builder.rb,
lib/uniword/builder/watermark_builder.rb,
lib/uniword/builder/table_cell_builder.rb,
lib/uniword/builder/bibliography_builder.rb,
lib/uniword/builder/header_footer_builder.rb

Overview

Builder module provides a construction API for OOXML models.

The Builder API orchestrates the creation and manipulation of OOXML model objects without adding convenience methods to the model classes themselves.

Examples:

Build a document

doc = Uniword::Builder::DocumentBuilder.new
doc.paragraph { |p| p << 'Hello World' }
doc.save('output.docx')

Load and modify a document

doc = Uniword::Builder::DocumentBuilder.from_file('input.docx')
doc.paragraph { |p| p << 'Appended content' }
doc.save('output.docx')

Defined Under Namespace

Modules: DeterministicId, HasBorders, HasShading, RunUtils Classes: BaseBuilder, BibliographyBuilder, ChartBuilder, CommentBuilder, DocumentBuilder, FootnoteBuilder, HeaderFooterBuilder, ImageBuilder, ListBuilder, NumberingBuilder, ParagraphBuilder, RunBuilder, SdtBuilder, SectionBuilder, StyleBuilder, TableBuilder, TableCellBuilder, TableRowBuilder, ThemeBuilder, TocBuilder, WatermarkBuilder

Class Method Summary collapse

Class Method Details

.date_field(format: "M/d/yyyy") ⇒ Wordprocessingml::Paragraph

Factory: creates a paragraph containing a DATE field

Parameters:

  • format (String) (defaults to: "M/d/yyyy") —

    Date format (default 'M/d/yyyy')

Returns:



198
199
200
 
# File 'lib/uniword/builder.rb', line 198

def self.date_field(format: "M/d/yyyy")
  build_field_paragraph(" DATE \\@ \"#{format}\" ")
end

.floating_image(path, width: nil, height: nil, align: nil, wrap: :square, behind_text: false) ⇒ Wordprocessingml::Drawing

Factory: creates a floating image Drawing NOTE: This does NOT register the image in the document's image_parts. Use DocumentBuilder#floating_image instead for proper DOCX packaging.

Parameters:

  • path (String) —

    Path to image file

  • width (Integer, nil) (defaults to: nil) —

    Width in EMU

  • height (Integer, nil) (defaults to: nil) —

    Height in EMU

  • align (Symbol, nil) (defaults to: nil) —

    Horizontal alignment

  • wrap (Symbol) (defaults to: :square) —

    Text wrapping style

  • behind_text (Boolean) (defaults to: false) —

    Place behind text

Returns:



136
137
138
139
140
141
 
# File 'lib/uniword/builder.rb', line 136

def self.floating_image(path, width: nil, height: nil, align: nil,
                        wrap: :square, behind_text: false)
  ImageBuilder.create_floating(nil, path, width: width, height: height,
                                          align: align, wrap: wrap,
                                          behind_text: behind_text)
end

.hyperlink(target, text = nil, **options) ⇒ Wordprocessingml::Hyperlink

Factory: creates a Hyperlink with optional text run

Parameters:

  • target (String) —

    URL or bookmark target

  • text (String, nil) (defaults to: nil) —

    Link display text

  • color (String) —

    Link color (hex, default '0000FF')

  • underline (Boolean) —

    Underline the link (default true)

Returns:



87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/uniword/builder.rb', line 87

def self.hyperlink(target, text = nil, **options)
  hl = Wordprocessingml::Hyperlink.new
  hl.target = target
  if text
    color = options.fetch(:color, "0000FF")
    ul = options.fetch(:underline, true)
    run = self.text(text, color: color, underline: ul ? "single" : nil)
    hl.runs << run
  end
  hl
end

.image(path, width: nil, height: nil) ⇒ Wordprocessingml::Run

Factory: creates a Run containing an inline image Drawing NOTE: This does NOT register the image in the document's image_parts. Use DocumentBuilder#image instead for proper DOCX packaging.

Parameters:

  • path (String) —

    Path to image file

  • width (Integer, nil) (defaults to: nil) —

    Width in EMU

  • height (Integer, nil) (defaults to: nil) —

    Height in EMU

Returns:



121
122
123
 
# File 'lib/uniword/builder.rb', line 121

def self.image(path, width: nil, height: nil)
  ImageBuilder.create_drawing(nil, path, width: width, height: height)
end

.line_break ⇒ Wordprocessingml::Run

Factory: creates a Run containing a line break

Returns:



174
175
176
177
178
 
# File 'lib/uniword/builder.rb', line 174

def self.line_break
  run = Wordprocessingml::Run.new
  run.break = Wordprocessingml::Break.new(type: "line")
  run
end

.page_break ⇒ Wordprocessingml::Run

Factory: creates a page break Run

Returns:



146
147
148
149
150
 
# File 'lib/uniword/builder.rb', line 146

def self.page_break
  run = Wordprocessingml::Run.new
  run.break = Wordprocessingml::Break.new(type: "page")
  run
end

.page_number_field ⇒ Wordprocessingml::Paragraph

Factory: creates a paragraph containing a PAGE field

Returns:



183
184
185
 
# File 'lib/uniword/builder.rb', line 183

def self.page_number_field
  build_field_paragraph(" PAGE ")
end

.tab ⇒ Wordprocessingml::Run

Factory: creates a Run containing a tab character. Use this with ParagraphBuilder#<< to append a tab to a paragraph.

Returns:

See Also:



157
158
159
160
161
 
# File 'lib/uniword/builder.rb', line 157

def self.tab
  run = Wordprocessingml::Run.new
  run.tab = tab_element
  run
end

.tab_element ⇒ Wordprocessingml::Tab

Factory: creates a bare Tab element for direct assignment to Run#tab. Most callers should use .tab instead, which wraps the Tab in a Run.

Returns:



167
168
169
 
# File 'lib/uniword/builder.rb', line 167

def self.tab_element
  Wordprocessingml::Tab.new
end

.tab_stop(position:, alignment: :left, leader: nil) ⇒ Properties::TabStop

Factory: creates a TabStop

Parameters:

  • position (Integer) —

    Tab position in twips

  • alignment (Symbol, String) (defaults to: :left) —

    :left, :center, :right, :decimal

  • leader (String, nil) (defaults to: nil) —

    Leader character style

Returns:



105
106
107
108
109
110
111
 
# File 'lib/uniword/builder.rb', line 105

def self.tab_stop(position:, alignment: :left, leader: nil)
  Properties::TabStop.new(
    position: position,
    alignment: alignment.to_s,
    leader: leader,
  )
end

.text(content, **formatting) ⇒ Wordprocessingml::Run

Factory: creates a Run with optional formatting

Parameters:

  • content (String) —

    Text content

  • bold (Boolean) —

    Bold formatting

  • italic (Boolean) —

    Italic formatting

  • underline (String, Boolean) —

    Underline style

  • color (String) —

    Font color (hex)

  • size (Integer) —

    Font size in points

  • font (String) —

    Font name

  • highlight (String) —

    Highlight color

  • strike (Boolean) —

    Strikethrough

  • small_caps (Boolean) —

    Small caps

  • caps (Boolean) —

    All caps

Returns:



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/uniword/builder.rb', line 58

def self.text(content, **formatting)
  run = Wordprocessingml::Run.new(text: content)
  return run if formatting.empty?

  props = Wordprocessingml::RunProperties.new
  props.bold = Properties::Bold.new(value: true) if formatting[:bold]
  props.italic = Properties::Italic.new(value: true) if formatting[:italic]
  if formatting[:underline]
    val = formatting[:underline] == true ? "single" : formatting[:underline].to_s
    props.underline = Properties::Underline.new(value: val)
  end
  props.color = Properties::ColorValue.new(value: formatting[:color].to_s) if formatting[:color]
  props.size = Properties::FontSize.new(value: formatting[:size].to_i * 2) if formatting[:size]
  props.font = formatting[:font] if formatting[:font]
  props.highlight = Properties::Highlight.new(value: formatting[:highlight].to_s) if formatting[:highlight]
  props.strike = Properties::Strike.new(value: true) if formatting[:strike]
  props.small_caps = Properties::SmallCaps.new(value: true) if formatting[:small_caps]
  props.caps = Properties::Caps.new(value: true) if formatting[:caps]
  run.properties = props
  run
end

.time_field(format: "h:mm:ss am/pm") ⇒ Wordprocessingml::Paragraph

Factory: creates a paragraph containing a TIME field

Parameters:

  • format (String) (defaults to: "h:mm:ss am/pm") —

    Time format (default 'h:mm:ss am/pm')

Returns:



206
207
208
 
# File 'lib/uniword/builder.rb', line 206

def self.time_field(format: "h:mm:ss am/pm")
  build_field_paragraph(" TIME \\@ \"#{format}\" ")
end

.total_pages_field ⇒ Wordprocessingml::Paragraph

Factory: creates a paragraph containing a NUMPAGES field

Returns:



190
191
192
 
# File 'lib/uniword/builder.rb', line 190

def self.total_pages_field
  build_field_paragraph(" NUMPAGES ")
end