Class: Krill::ShowBlock

Inherits:
Object
  • Object
show all
Defined in:
lib/krill/show_block.rb

Overview

The ShowBlock class implements the methods inside show blocks, which are used to interact with the technician. When a show block is encountered, it is used to construct a page of instructions for the technician. Execution is suspended until the user clicks "OK" in the protocol. The show method returns a ShowResponse object that contains any information entered by the user via get, select, or table inputs.

Examples:

A show block with everything

item = Item.last
response = show do
  title "Title describing what the technician should do in this step"
  note "Body text goes inside notes describing the details of this step of the protocol"
  warning "A warning will be displayed vibrantly"
  check "A checkbox will precede this text, and the user must click it to proceed"
  bullet "For bullet lists"
  table [ [ "A", "B" ], [ 1, 2 ] ]
  item item
  separator
  image "path/to/s3/image.jpg"
  timer initial: { hours: 0, minutes: 2, seconds: 30 }
  upload var: "my_upload"
  get "text", var: "y", label: "Enter a string", default: "Hello World"
  get "number", var: "z", label: "Enter a number", default: 555
  select [ "A", "B", "C" ], var: "choice", label: "Choose something", default: 1
end

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(m, *args, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



303
304
305
306
307
308
309
310
311
 
# File 'lib/krill/show_block.rb', line 303

def method_missing(m, *args, &block)
  raise "Cannot call 'show' within a show block." if m == :show

  if @base.methods.include?(m)
    @base.send(m, *args, &block)
  else
    super
  end
end

Instance Method Details

#bullet(str) ⇒ void

This method returns an undefined value.

Put the string s on the page, with a bullet in front of it, as in a bullet list. If an array of strings is passed, then a bullet is made for each element of the array.

Parameters:

  • str (String, Array<String>) 


91
92
93
 
# File 'lib/krill/show_block.rb', line 91

def bullet(str)
  [*str].each { |s| @parts.push(bullet: s) }
end

#check(str) ⇒ void

This method returns an undefined value.

Put the string s on the page, with a clickable checkbox in front of it. The user will need to click all checkboxes on a given page before the "OK" button is enabled. If an array of strings is passed, then a checkbox is made for each element of the array.

Parameters:

  • str (String, Array<String>) 


83
84
85
 
# File 'lib/krill/show_block.rb', line 83

def check(str)
  [*str].each { |s| @parts.push(check: s) }
end

#get(type, opts = {}) ⇒ void

This method returns an undefined value.

Display an input box to the user to obtain data of some kind. If no options are supplied, then the data is stored in a ShowResponse object returned by the show function with a key called something like get_12 or get_13 (for get number 12 or get number 13). The name of the variable name can be specified via the var option. A label for the input box can also be specified.

Examples:

data = show {
  title "An input example"
  get "text", var: "y", label: "Enter a string", default: "Hello World"
  get "number", var: "z", label: "Enter a number", default: 555
}

y = data[:y]
z = data[:z]

Parameters:

  • type (String) —

    Either "text" or "number"

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

    a customizable set of options

Options Hash (opts):

  • :var (String) —

    The name of the resulting value in the ShowResponse object

  • :label (String) —

    The label shown next to the input box

  • :default (String) —

    The default value if the type is text

  • :default (Float) —

    The default value if the type is number



243
244
245
246
247
248
249
250
251
252
 
# File 'lib/krill/show_block.rb', line 243

def get(type, opts = {})
  raise "First argument to get should be either 'number' or 'text'" unless type == 'number' || type == 'text'

  options = {
    var: "get_#{@@get_counter}",
    label: "Enter a #{type}"
  }
  @@get_counter += 1
  @parts.push(input: (options.merge opts).merge(type: type))
end

#image(name) ⇒ Object

Display the image pointed to by name on the page. The name argument will be prepended by the URL to the S3 url defined by Bioturk::Application.config.image_server_interface in config/initializers/aquarium.rb

Examples:

image "containers/bottle_1_liter.jpg"

Parameters:

  • name (String) 


157
158
159
 
# File 'lib/krill/show_block.rb', line 157

def image(name)
  @parts.push(image: "#{Bioturk::Application.config.image_server_interface}#{name}")
end

#item(i) ⇒ void

This method returns an undefined value.

Display information about the item i -- its id, its location, its object type, and its sample type (if any) -- so that the user can find it.

Parameters:



133
134
135
 
# File 'lib/krill/show_block.rb', line 133

def item(i)
  @parts.push(take: i)
end

#note(str) ⇒ void

This method returns an undefined value.

Put the string s in a smaller font on the page. Often called several times. If an array of strings is passed, then a note is made for each element of the array.

Parameters:

  • str (String, Array<String>) 


59
60
61
 
# File 'lib/krill/show_block.rb', line 59

def note(str)
  [*str].each { |s| @parts.push(note: s) }
end

#select(choices, opts = {}) ⇒ void

This method returns an undefined value.

Display a selection of choices for the user. The options are the same as for get. For example,

param choices [List] A list of choices, either all strings or all numbers

Examples:

data = show {
  title "A Select Example"
  select [ "A", "B", "C" ], var: "choice", label: "Choose something", default: 1
}

choice = data[:choice]

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • :var (String) —

    The name of the resulting value in the ShowResponse object

  • :label (String) —

    The label shown next to the input box

  • :default (String) —

    The default value if the type is text

  • :default (Float) —

    The default value if the type is number



283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/krill/show_block.rb', line 283

def select(choices, opts = {})
  choices = choices.uniq
  raise 'First argument to select should be an array of numbers or strings' unless ShowBlock.is_proper_array choices

  options = {
    var: "select_#{@@select_counter}",
    label: 'Choose',
    multiple: false
  }
  @@select_counter += 1
  @parts.push(select: (options.merge opts).merge(choices: choices))
end

#separator ⇒ void

This method returns an undefined value.

Display a break between other shown elements, such as between two notes.



146
147
148
 
# File 'lib/krill/show_block.rb', line 146

def separator
  @parts.push(separator: true)
end

#table(m) ⇒ void

This method returns an undefined value.

Display a table represented by the matrix t. The method takes a 2x2 list of either numbers, strings, or hashes. In the case of hashes, the following fields can be present.

content: A number or string check: Whether the entry is checkable, true or false style: A hash containing css

See the Operations documentation for more information about how to construct tables automatically based on the inputs and outputs to a protocol's operation.

Examples:

show {
  table [ [ "A", "B" ], [ 1, 2 ] ]
}
m = [
  [ "A", "Very", "Nice", { content: "Table", style: { color: "#f00" } } ],
  [ { content: 1, check: true }, 2, 3, 4 ]
]
show {
  title "A Table"
  table m
}

Parameters:

  • m (List) 


121
122
123
124
125
126
127
 
# File 'lib/krill/show_block.rb', line 121

def table(m)
  if m.class == Table
    @parts.push(table: m.all.render)
  else
    @parts.push(table: m)
  end
end

#timer(opts = {}) ⇒ void

This method returns an undefined value.

Show a rudimentary timer. By default, the timer starts at one minute and counts down. It starts beeping when it gets to zero, and keeps beeping until the user clicks "OK". You can specify the starting number of hours, minutes, and seconds, with for example The initial option can be used to set the initial time on the timer and has field hours, minutes, and seconds, all numerical.

Examples:

timer initial: { hours: 0, minutes: 20, seconds: 30}

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • :initial (Hash) 


171
172
173
174
175
176
177
178
 
# File 'lib/krill/show_block.rb', line 171

def timer(opts = {})
  options = {
    initial: { hours: 0, minutes: 1, seconds: 0 },
    final: { hours: 0, minutes: 0, seconds: 0 },
    direction: 'down'
  }.merge opts
  @parts.push(timer: options)
end

#title(str) ⇒ void

This method returns an undefined value.

Put the string s at the top of the page. Usually only called once in a given call to show.

Parameters:

  • str (String) 


51
52
53
 
# File 'lib/krill/show_block.rb', line 51

def title(str)
  @parts.push(title: str)
end

#upload(opts = {}) ⇒ void

This method returns an undefined value.

Upload a file. The optional name specified by the :var option can be used to retrieve the upload.

See the [ShowResponse] documentation for how to manipulate uploads.

Examples:

response = show do
  upload var: "my var"
end

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • :var (String) 


189
190
191
192
193
194
195
 
# File 'lib/krill/show_block.rb', line 189

def upload(opts = {})
  options = {
    var: "upload_#{@@upload_counter}"
  }
  @@upload_counter += 1
  @parts.push(upload: options.merge(opts))
end

#warning(str) ⇒ void

This method returns an undefined value.

Put the string s in bold, eye catching font on the page in hopes that the user might notice it and heed your advice.

Parameters:

  • str (String) 


74
75
76
 
# File 'lib/krill/show_block.rb', line 74

def warning(str)
  @parts.push(warning: str)
end