Class: Uniword::Wordprocessingml::DocumentRoot

Inherits:
Lutaml::Model::Serializable
  • Object
show all
Includes:
DocumentInput, FeatureFacade, DocumentStyling
Defined in:
lib/uniword/wordprocessingml/document_root.rb,
lib/uniword/wordprocessingml/document_root/feature_facade.rb

Overview

Root element of a WordprocessingML document

Generated from OOXML schema: wordprocessingml.yml Element: <w:document>

Defined Under Namespace

Modules: FeatureFacade

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from DocumentStyling

#apply_color_scheme, #apply_font_scheme, #apply_page_setup, #apply_styles_from, #apply_styleset, #apply_template, #apply_theme, #apply_theme_file, #apply_theme_from, #auto_transition_theme, #remove_style, #remove_unused_styles, #rename_style, #replace_font

Methods included from FeatureFacade

#accept_all_changes, #add_comment, #add_footer, #add_header, #add_watermark, #clear_comments, #diff, #extract_images, #generate_toc, #insert_image, #insert_toc, #list_comments, #list_footers, #list_headers, #list_images, #list_watermarks, #protect, #protection_active?, #protection_info, #reject_all_changes, #remove_footers, #remove_headers, #remove_image, #remove_watermark, #spellcheck, #unprotect, #update_toc, #watermark?

Instance Attribute Details

#allocator ⇒ Object

Central ID allocator — preserves IDs across build/save cycle



107
108
109
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 107

def allocator
  @allocator
end

#app_properties ⇒ Uniword::Ooxml::AppProperties

Get app_properties (lazy initialization)

Returns:



210
211
212
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 210

def app_properties
  @app_properties ||= Uniword::Ooxml::AppProperties.new
end

#bibliography_sources ⇒ Object

Bibliography sources for sources.xml



101
102
103
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 101

def bibliography_sources
  @bibliography_sources
end

#bookmarks ⇒ Hash{String => Object}

Get bookmarks from document paragraphs

Returns:

  • (Hash{String => Object}) —

    Map of bookmark names to bookmark data



342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 342

def bookmarks
  result = {}
  return result unless body&.paragraphs

  body.paragraphs.each do |para|
    para.bookmark_starts&.each do |bs|
      result[bs.name.to_s] = bs if bs.name
    end
  end
  result
end

#comments ⇒ Object

Additional attributes for DOCX metadata (not part of document.xml) These are stored in separate files within the DOCX package



97
98
99
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 97

def comments
  @comments
end

#content_types ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def content_types
  @content_types
end

#core_properties ⇒ Uniword::Ooxml::CoreProperties

Get core_properties (lazy initialization)

Returns:



231
232
233
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 231

def core_properties
  @core_properties ||= Uniword::Ooxml::CoreProperties.new
end

#custom_properties ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def custom_properties
  @custom_properties
end

#custom_xml_items ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def custom_xml_items
  @custom_xml_items
end

#document_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def document_rels
  @document_rels
end

#endnotes ⇒ Object

Footnotes and endnotes (separate XML parts in DOCX package)



99
100
101
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 99

def endnotes
  @endnotes
end

#endnotes_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def endnotes_rels
  @endnotes_rels
end

#font_table ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def font_table
  @font_table
end

#footnotes ⇒ Object

Footnotes and endnotes (separate XML parts in DOCX package)



99
100
101
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 99

def footnotes
  @footnotes
end

#footnotes_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def footnotes_rels
  @footnotes_rels
end

#numbering_configuration ⇒ Object

Accessor for numbering_configuration (lazy init for builder API)



215
216
217
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 215

def numbering_configuration
  @numbering_configuration ||= NumberingConfiguration.new
end

#package_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def package_rels
  @package_rels
end

#raw_html ⇒ Object

Additional attributes for DOCX metadata (not part of document.xml) These are stored in separate files within the DOCX package



97
98
99
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 97

def raw_html
  @raw_html
end

#revisions ⇒ Object

Additional attributes for DOCX metadata (not part of document.xml) These are stored in separate files within the DOCX package



97
98
99
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 97

def revisions
  @revisions
end

#settings ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def settings
  @settings
end

#settings_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def settings_rels
  @settings_rels
end

#styles_configuration ⇒ Object

Lazy initialization for styles_configuration



241
242
243
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 241

def styles_configuration
  @styles_configuration ||= StylesConfiguration.new
end

#theme ⇒ Object

Additional attributes for DOCX metadata (not part of document.xml) These are stored in separate files within the DOCX package



97
98
99
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 97

def theme
  @theme
end

#theme_rels ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def theme_rels
  @theme_rels
end

#web_settings ⇒ Object

Round-trip parts (copied from DocxPackage during load)



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

def web_settings
  @web_settings
end

Instance Method Details

#chart_parts ⇒ Docx::PartCollection

Chart parts to embed in the DOCX package, keyed by rId.

Returns:



171
172
173
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 171

def chart_parts
  @chart_parts ||= Docx::PartCollection.new(:r_id, Docx::ChartPart)
end

#chart_parts=(value) ⇒ Object

Bulk-assign chart parts (Hash of rId => ChartPart/hash; nil clears).



176
177
178
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 176

def chart_parts=(value)
  chart_parts.replace_all(value)
end

#document_stats ⇒ Hash

Returns Document statistics (paragraphs, tables, images).

Returns:

  • (Hash) —

    Document statistics (paragraphs, tables, images)



308
309
310
311
312
313
314
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 308

def document_stats
  {
    paragraphs: paragraphs.count,
    tables: tables.count,
    images: images.count,
  }
end

#embeddings ⇒ Docx::PartCollection

OLE/embedded object binaries (word/embeddings/*), keyed by target.

Returns:



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

def embeddings
  @embeddings ||= Docx::PartCollection.new(:target, Docx::Part)
end

#embeddings=(value) ⇒ Object

Bulk-assign embeddings (Hash of target => Part/binary; nil clears).



188
189
190
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 188

def embeddings=(value)
  embeddings.replace_all(value)
end

#footers ⇒ Docx::HeaderFooterView

Footers view over the unified store.

Returns:



145
146
147
148
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 145

def footers
  @footers ||=
    Docx::HeaderFooterView.new(header_footer_parts, :footer)
end

#footers=(value) ⇒ Object

Bulk-assign footers (see #headers=).



151
152
153
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 151

def footers=(value)
  footers.replace(value)
end

#header_footer_parts ⇒ Docx::HeaderFooterPartCollection

Unified header/footer part store — the single storage path for both round-tripped and builder-created headers/footers.

Returns:



117
118
119
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 117

def header_footer_parts
  @header_footer_parts ||= Docx::HeaderFooterPartCollection.new
end

#header_footer_parts=(parts) ⇒ Object

Replace the whole store (accepts HeaderFooterPart objects and legacy part hashes).



123
124
125
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 123

def header_footer_parts=(parts)
  header_footer_parts.replace_all(parts)
end

#headers ⇒ Docx::HeaderFooterView

Headers view over the unified store (Hash-style by sectPr type, Array-style over parts).

Returns:



131
132
133
134
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 131

def headers
  @headers ||=
    Docx::HeaderFooterView.new(header_footer_parts, :header)
end

#headers=(value) ⇒ Object

Bulk-assign headers (nil clears; Hash of type => model; Array of models/parts).



138
139
140
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 138

def headers=(value)
  headers.replace(value)
end

#image_parts ⇒ Docx::PartCollection

Image parts (word/media/* binaries), keyed by rId.

Returns:



158
159
160
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 158

def image_parts
  @image_parts ||= Docx::PartCollection.new(:r_id, Docx::ImagePart)
end

#image_parts=(value) ⇒ Object

Bulk-assign image parts (Hash of rId => ImagePart/legacy part hash; nil clears).



164
165
166
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 164

def image_parts=(value)
  image_parts.replace_all(value)
end

#images ⇒ Array<Drawing>

Get all drawings (image references) from the document. Walks all paragraphs and collects Drawing elements from runs.

Returns:

  • (Array<Drawing>) —

    All drawing elements in document



299
300
301
302
303
304
305
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 299

def images
  return [] unless body&.paragraphs

  body.paragraphs.flat_map do |para|
    (para.runs || []).flat_map(&:drawings)
  end.compact
end

#inspect ⇒ String

Apply theme to document

Custom inspect for readable output

Returns:

  • (String) —

    Human-readable representation



359
360
361
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 359

def inspect
  "#<#{self.class} @body=...>"
end

#numbering_configuration_loaded? ⇒ Boolean

Whether numbering_configuration was explicitly loaded from source (vs lazily created for builder API)

Returns:

  • (Boolean) 


224
225
226
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 224

def numbering_configuration_loaded?
  !!@numbering_configuration
end

#paragraphs ⇒ Array<Paragraph>

Get all paragraphs (convenience accessor)

Returns:

  • (Array<Paragraph>) —

    All paragraphs in document



284
285
286
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 284

def paragraphs
  body&.paragraphs || []
end

#raw_parts ⇒ Docx::PartCollection

Raw passthrough parts (unmodelled package parts carried byte-for-byte), keyed by package path. Mirrored from the package on load and back on save via the registry-driven document↔package copies (:raw_parts definition).

Returns:



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

def raw_parts
  @raw_parts ||= Docx::PartCollection.new(:path, Docx::RawPart)
end

#raw_parts=(value) ⇒ Object

Bulk-assign raw parts (Hash of path => RawPart/hash; nil clears).



203
204
205
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 203

def raw_parts=(value)
  raw_parts.replace_all(value)
end

#save(path, format: :auto, profile: nil, validate: nil) ⇒ void

This method returns an undefined value.

Save document to file

Parameters:

  • path (String) —

    Output file path

  • format (Symbol) (defaults to: :auto) —

    Format (:docx, :mhtml, :auto)

  • profile (Docx::Profile, nil) (defaults to: nil) —

    Profile for reconciliation

  • validate (Boolean, nil) (defaults to: nil) —

    Run the package integrity gate before writing; nil falls back to Uniword.configuration.validate_on_save



256
257
258
259
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 256

def save(path, format: :auto, profile: nil, validate: nil)
  writer = DocumentWriter.new(self)
  writer.save(path, format: format, profile: profile, validate: validate)
end

#tables ⇒ Array<Table>

Get all tables (convenience accessor)

Returns:

  • (Array<Table>) —

    All tables in document



291
292
293
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 291

def tables
  body&.tables || []
end

#text ⇒ String

Get all paragraph text

Returns:

  • (String) —

    Combined text from all paragraphs



275
276
277
278
279
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 275

def text
  return "" unless body&.paragraphs

  body.paragraphs.map(&:text).join("\n")
end

#title ⇒ Object

Get document title (delegates to core_properties)



236
237
238
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 236

def title
  core_properties.title
end

#to_file(path, profile: nil, validate: nil) ⇒ void

This method returns an undefined value.

Save document to DOCX file using DocxPackage

Parameters:

  • path (String) —

    Output file path

  • profile (Docx::Profile, nil) (defaults to: nil) —

    Profile for reconciliation

  • validate (Boolean, nil) (defaults to: nil) —

    Run the package integrity gate before writing; nil falls back to Uniword.configuration.validate_on_save



268
269
270
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 268

def to_file(path, profile: nil, validate: nil)
  Docx::Package.to_file(self, path, profile: profile, validate: validate)
end

#to_html_document ⇒ String

Convert OOXML document to HTML document

Returns:

  • (String) —

    HTML document content



366
367
368
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 366

def to_html_document
  Uniword::Transformation::OoxmlToHtmlConverter.document_to_html(self)
end

#to_xml(options = {}) ⇒ Object

Override to_xml to sync element_order on child collections before serialization. lutaml-model's compiled serializer may bypass child #to_xml when serializing nested elements, so we sync here at the DocumentRoot level.



88
89
90
91
92
93
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 88

def to_xml(options = {})
  body&.sync_element_order_for_serialization
  footnotes&.sync_element_order if footnotes
  endnotes&.sync_element_order if endnotes
  super
end

#valid? ⇒ Boolean

Check if document structure is valid. Runs model-level validation rules via Validation::Engine. Use the verify CLI command for full OPC + XSD + semantic validation.

Returns:

  • (Boolean) —

    true if document has valid structure



321
322
323
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 321

def valid?
  validation_errors.empty?
end

#validation_errors ⇒ Array<String>

Get structural validation errors.

Returns:

  • (Array<String>) —

    Error messages



328
329
330
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 328

def validation_errors
  structural_issues.select(&:error?).map(&:message)
end

#validation_warnings ⇒ Array<String>

Get structural validation warnings.

Returns:

  • (Array<String>) —

    Warning messages



335
336
337
 
# File 'lib/uniword/wordprocessingml/document_root.rb', line 335

def validation_warnings
  structural_issues.reject(&:error?).map(&:message)
end