class DebugBar::Base

Overview

DebugBar::Base provides the base methods for all debug bars.

At it’s core, a DebugBar is instantiated with initialize, gets callbacks added with add_callback, and then is rendered with render.

Additionally, RecipeBook classes or instance may be added to the DebugBar via add_recipe_book so that pre-made callbacks may be easily added to the DebugBar instance via add_callbacks.

See the README for example usage.

Subclassing

This class is often subclassed to give DebugBars with special behaviors. If you make a subclass, define private overrides to these methods:

default_recipe_books

Provide a list of recipe books to make available to all instances.

default_recipes

Add a list of recipe callbacks to all instances.

template_search_paths

Override the default formatting template search path.

Constants

TEMPLATE_SEARCH_PATHS

The search path for formatting templates, such as the layout and callback box. NOTE: This is separate from templates that are used in recipes!

Attributes

callbacks[R]

Returns a copy of the raw list of callbacks.

recipe_books[R]

Returns a copy of the list of recipe book instances.

Public Class Methods

new(*recipes) { |self| ... } click to toggle source

Initialize a new debug bar. This may optionally take one or more recipe symbols as arguments.

# File lib/debug-bar/base.rb, line 41
def initialize(*recipes)
  #Initialize registration variables.
  @callbacks = []
  @recipe_books = []
  # Register defaults.
  default_recipe_books.each {|book| add_recipe_book(book)}
  default_recipes.each {|recipe| add_recipe(recipe)}
  # Give a chance for custom configuration, including addition of books.
  yield self if block_given?
  # Now we can add user listed recipes.
  recipes.each {|recipe| add_recipe(recipe)}
end

Public Instance Methods

add(recipe=nil, *args, &callback)
Alias for: add_callback
add_book(book)
Alias for: add_recipe_book
add_callback(recipe=nil, *args, &callback) click to toggle source

Adds a callback.

Takes either a recipe (by symbol) or a block.

The block takes a single argument, the binding of the render context, and should return either a string, or an array of [title, content, opts].

Advanced users can call a recipe by name, and provide additional arguments to configure the recipe further. These arguments are defined by the recipe factory method, but usually are via an options hash and/or a block.

Returns self to support functional programming styles.

# File lib/debug-bar/base.rb, line 94
def add_callback(recipe=nil, *args, &callback)
  callback_proc = recipe.nil? ? callback : recipe_callback(recipe, *args, &callback)
  raise ArgumentError, "Expected callback to respond to `call': #{callback_proc.inspect}", caller unless callback_proc.respond_to?(:call)
  @callbacks << callback_proc
  return self
end
Also aliased as: add_recipe, add
add_recipe(recipe=nil, *args, &callback)
Alias for: add_callback
add_recipe_book(book) click to toggle source

Adds a recipe book class or instance to the recipe book list for this debug bar.

Returns self to support functional programming styles.

# File lib/debug-bar/base.rb, line 64
def add_recipe_book(book)
  @recipe_books << (book.kind_of?(Class) ? book.new : book)
  return self
end
Also aliased as: add_book
recipe_callback(recipe, *args, &block) click to toggle source

Returns the most recently added occurance of the given recipe.

# File lib/debug-bar/base.rb, line 76
def recipe_callback(recipe, *args, &block)
  book = @recipe_books.reverse.find {|book| book.include?(recipe)}
  raise ArgumentError, "Could not find recipe #{recipe.inspect}", caller if book.nil?
  return book.recipe(recipe, *args, &block)
end
recipes() click to toggle source

Returns the list of recipes recognized by this debug bar.

# File lib/debug-bar/base.rb, line 71
def recipes
  return @recipe_books.inject([]) {|list,book| list | book.recipes}
end
render(eval_binding) click to toggle source

Renders the debug bar with the given binding.

# File lib/debug-bar/base.rb, line 104
def render(eval_binding)
  # Decorate the binding here (NOT in private methods where we don't want automatic behavior)!
  eval_binding.extend(DebugBar::Ext::Binding)
  return render_layout(eval_binding)
end

Private Instance Methods

default_recipe_books() click to toggle source

An initialization callback for adding default recipe books to instances; this should return an array of recipe book classes or instances.

On the base class, this returns an empty array; subclasses should override this.

# File lib/debug-bar/base.rb, line 116
def default_recipe_books
  return []
end
default_recipes() click to toggle source

An initialization callback for adding default recipes to the callbacks array.

On the base class, this returns an empty array; subclasses should override this.

# File lib/debug-bar/base.rb, line 124
def default_recipes
  return []
end
read_template(template) click to toggle source

Looks for the given remplate name within the template search paths, and returns a string containing its contents. The name may be a symbol or string.

Template names automatically have ‘.html.erb’ appended to them, so call

read_template(:foo)

instead of

read_template('foo.html.erb')
# File lib/debug-bar/base.rb, line 145
def read_template(template)
  template_name = "#{template}.html.erb"
  template_path = template_search_paths.map {|base_path| (base_path + template_name).expand_path}.find {|p| p.exist? && p.file?}
  raise ArgumentError, "Unknown template #{template_name.inspect}.  Not in #{template_search_paths.inspect}", caller if template_path.nil?
  return template_path.read
end
render_callback(callback, eval_binding) click to toggle source

Renders the given callback in the given binding.

# File lib/debug-bar/base.rb, line 165
def render_callback(callback, eval_binding)
  # Get the result of the callback
  obj = begin
          callback.respond_to?(:call) ? callback.call(eval_binding) : callback
        rescue Exception => error
          render_error_callback(error)
        end

  # Extract the title, content, and opts from the result
  title, content, opts = case obj
  when Array
    obj
  else
    ['Debug', obj.to_s, {}]
  end
  opts ||= {}

  # reverse merge the opts
  default_hidden = opts[:id].nil? ? false : !cookie_include?(opts[:id], eval_binding)
  opts = {:hidden => default_hidden}.merge(opts||{})

  # Render the callback in a box
  return Erubis::Eruby.new( read_template(:callback_box) ).result(:title => title, :content => content, :opts => opts).html_safe
end
render_callbacks(callbacks, eval_binding) click to toggle source

Returns the contactinated set of rendered callbacks usnig the given binding.

# File lib/debug-bar/base.rb, line 160
def render_callbacks(callbacks, eval_binding)
  return @callbacks.map {|callback| render_callback(callback, eval_binding)}.join("\n")
end
render_error_callback(error, opts={}) click to toggle source
# File lib/debug-bar/base.rb, line 190
def render_error_callback(error, opts={})
  return [
    opts.fetch(:title, '**ERROR'),
    Erubis::Eruby.new(read_template(:error)).result(:error => error).html_safe,
    {}
  ]
end
render_layout(eval_binding) click to toggle source

Renders the callbacks and then renders the layout–all in the given binding–inserting the callbacks into the layout; returns an html_safe string.

# File lib/debug-bar/base.rb, line 154
def render_layout(eval_binding)
  content = render_callbacks(@callbacks, eval_binding)
  return Erubis::Eruby.new(read_template(:layout)).result(:content => content).html_safe
end
template_search_paths() click to toggle source

Returns the template search paths for this instance.

Paths should be Pathname instances

Subclasses may override this to change the search path for the formatting templates such as the layout and callback_box templates.

# File lib/debug-bar/base.rb, line 134
def template_search_paths
  return TEMPLATE_SEARCH_PATHS
end