Module: Howdoc::Recorder

Defined in:
lib/howdoc/recorder.rb

Overview

The public recording API. Anything that wants to appear in a guide goes through here -- the Capybara wrappers the gem ships with, and equally an application's own helpers, which the engine cannot and should not know about. Every method is a no-op when documentation is switched off, so call sites need no guards of their own.

Constant Summary collapse

OPTION_KEYS =

Option keys the recorder consumes. They are removed from a Capybara option hash before it reaches Capybara, which would reject them.

%i[nodoc no_screenshot full_page screenshot].freeze

Class Method Summary collapse

Class Method Details

.capture(page, full_page: false, no_screenshot: false, marker: nil, marker_mode: :pointer) ⇒ Object

Illustrates the step recorded most recently. Separate from record because a screenshot has to be taken while the browser is still on the page, whereas the sentence can be composed at any time.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/howdoc/recorder.rb', line 57

def capture(page, full_page: false, no_screenshot: false, marker: nil, marker_mode: :pointer)
  return nil if no_screenshot || !recording?

  step = current.last_step || current.new_step
  filename = current.image_filename(step.number)

  Screenshot.capture(
    page,
    path: File.join(current.image_dir, filename),
    height: Howdoc.config.screenshot_height,
    full_page:, marker:, marker_mode:
  )

  step.screenshot = filename
end

.current ⇒ Object 



16
17
18
 
# File 'lib/howdoc/recorder.rb', line 16

def current
  Thread.current[:howdoc_document]
end

.current=(document) ⇒ Object 



20
21
22
 
# File 'lib/howdoc/recorder.rb', line 20

def current=(document)
  Thread.current[:howdoc_document] = document
end

.extract_options!(options) ⇒ Object

Removes the gem's own options from a Capybara option hash, mutating it, and returns them. Capybara raises on unknown options, so this has to happen before the wrapped call.



31
32
33
34
35
36
37
 
# File 'lib/howdoc/recorder.rb', line 31

def extract_options!(options)
  return {} unless options.is_a?(Hash)

  OPTION_KEYS.each_with_object({}) do |key, extracted|
    extracted[key] = options.delete(key) if options.key?(key)
  end
end

.record(action = nil, html: nil, arrival: false, nodoc: false, **payload) ⇒ Object

Records one instruction. action names an I18n key under howdoc.actions; the remaining keyword arguments are interpolated into it when the guide is written, once per language. Pass html: instead to supply already-rendered markup, for the rare step no sentence describes.

Values that read differently in different languages must not be resolved here: pass Howdoc::Narrator.field(locator) and the label is settled by each edition as it is written.



47
48
49
50
51
52
 
# File 'lib/howdoc/recorder.rb', line 47

def record(action = nil, html: nil, arrival: false, nodoc: false, **payload)
  return nil if nodoc || !recording?
  return nil if html.nil? && !Narrator.known?(action, current.locales)

  current.new_step(action:, payload:, html:, arrival:)
end

.record_and_capture(action, page:, options: {}, **payload) ⇒ Object

Convenience for the common shape: say what happens, then show it.



74
75
76
77
78
 
# File 'lib/howdoc/recorder.rb', line 74

def record_and_capture(action, page:, options: {}, **payload)
  step = record(action, nodoc: options[:nodoc], **payload)
  capture(page, full_page: options[:full_page], no_screenshot: options[:no_screenshot]) if step
  step
end

.recording? ⇒ Boolean

Returns:

  • (Boolean) 


24
25
26
 
# File 'lib/howdoc/recorder.rb', line 24

def recording?
  Howdoc.config.enabled? && !current.nil?
end