Module: Prawn::Accessibility::DocumentExtensions

Defined in:
lib/prawn/accessibility/document.rb

Overview

Instance methods included into Document to provide the high-level tagged-PDF (accessibility) API.

Tagging is opt-in: create the document with tagged: true (see the initializer shim at the bottom of this file). Everything here is built on Prawn/pdf-core's public API (renderer, state, min_version, before_render); no core class is patched to support it.

Examples:

pdf = Prawn::Document.new(tagged: true, language: 'en-US')
pdf.structure(:H1) { pdf.text 'Document Title' }
pdf.structure(:P)  { pdf.text 'Body paragraph text.' }
pdf.artifact       { pdf.text 'Page 1' } # not read by screen readers

Instance Method Summary collapse

Instance Method Details

#artifact(type: nil) { ... } ⇒ void

This method returns an undefined value.

Mark content as an artifact (decorative, not read by screen readers). Use for page numbers, decorative borders, backgrounds, watermarks.

Parameters:

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

    artifact type (:Pagination, :Layout, :Page, :Background)

Yields:

  • content to render as artifact



86
87
88
89
90
 
# File 'lib/prawn/accessibility/document.rb', line 86

def artifact(type: nil, &block)
  return yield if !tagged? || !block

  structure_tree.mark_artifact(artifact_type: type, &block)
end

#figure(alt_text:) { ... } ⇒ void

This method returns an undefined value.

Render an image wrapped in a Figure structure element with alt text.

Parameters:

  • alt_text (String) —

    alternative text for the image

Yields:

  • block that calls image() or other drawing methods



132
133
134
135
136
137
138
 
# File 'lib/prawn/accessibility/document.rb', line 132

def figure(alt_text:, &block)
  if tagged?
    structure(:Figure, Alt: alt_text, &block)
  else
    yield
  end
end

#heading(level, content, options = {}) ⇒ void

This method returns an undefined value.

Render a heading at the specified level.

Parameters:

  • level (Integer) —

    heading level 1-6

  • content (String) —

    heading text

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

    options passed to text()



98
99
100
101
102
103
104
105
 
# File 'lib/prawn/accessibility/document.rb', line 98

def heading(level, content, options = {})
  tag = :"H#{level}"
  if tagged?
    structure(tag) { text(content, options) }
  else
    text(content, options)
  end
end

#paragraph(content = nil, options = {}) { ... } ⇒ void

This method returns an undefined value.

Render text wrapped in a paragraph structure element.

Parameters:

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

    text to render. If nil, yields a block.

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

    options passed to text()

Yields:

  • optional block for complex paragraph content



113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/prawn/accessibility/document.rb', line 113

def paragraph(content = nil, options = {}, &block)
  if tagged?
    if block
      structure(:P, &block)
    else
      structure(:P) { text(content, options) }
    end
  elsif block
    yield
  else
    text(content, options)
  end
end

#structure(tag, attributes = {}) { ... } ⇒ void

This method returns an undefined value.

Wrap content in a structure element. The block's content will be associated with the given tag in the document's structure tree.

Can be nested — inner structure calls become children of the outer.

Parameters:

  • tag (Symbol) —

    PDF structure type (:Document, :Part, :Sect, :H1-:H6, :P, :L, :LI, :Lbl, :LBody, :Table, :TR, :TH, :TD, :Figure, :Formula, :Form, :Span, :Link, :Note, :BlockQuote, :Caption, :TOC, :TOCI, :Reference)

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

    optional attributes

Options Hash (attributes):

  • :Alt (String) —

    alternative text (for Figure, Formula)

  • :ActualText (String) —

    replacement text for screen readers (e.g., "required" for "*", "selected" for "X")

  • :Lang (String) —

    language override for this element

  • :Scope (Symbol) —

    table header scope (:Column, :Row, :Both)

Yields:

  • content to render inside this structure element



53
54
55
56
57
58
59
60
 
# File 'lib/prawn/accessibility/document.rb', line 53

def structure(tag, attributes = {}, &block)
  return yield if !tagged? || !block

  tree = structure_tree
  tree.begin_element(tag, attributes)
  tree.mark_content(tag, &block)
  tree.end_element
end

#structure_container(tag, attributes = {}) { ... } ⇒ void

This method returns an undefined value.

Wrap content in a structure element without marking the content directly. Use this for container elements (Table, TR, L, LI) where the children will each have their own marked content.

Parameters:

  • tag (Symbol) —

    PDF structure type

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

    optional attributes

Yields:

  • content to render inside this structure element



70
71
72
73
74
75
76
77
 
# File 'lib/prawn/accessibility/document.rb', line 70

def structure_container(tag, attributes = {}, &block)
  return yield if !tagged? || !block

  tree = structure_tree
  tree.begin_element(tag, attributes)
  yield
  tree.end_element
end

#structure_tree ⇒ Prawn::Accessibility::StructureTree?

The structure tree for this document, or nil if not tagged.

Returns:



25
26
27
 
# File 'lib/prawn/accessibility/document.rb', line 25

def structure_tree
  @accessibility_structure_tree
end

#tagged? ⇒ Boolean

Whether this document is tagged for accessibility.

Returns:

  • (Boolean) 


32
33
34
 
# File 'lib/prawn/accessibility/document.rb', line 32

def tagged?
  !@accessibility_structure_tree.nil?
end