Class: View::Formatter Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/view/formatter.rb

Overview

This class is abstract.

Subclass and override #format to implement your own formatter.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#blockObject (readonly)

Returns the value of attribute block



6
7
8
# File 'lib/view/formatter.rb', line 6

def block
  @block
end

#templateObject (readonly)

Returns the value of attribute template



6
7
8
# File 'lib/view/formatter.rb', line 6

def template
  @template
end

#valueObject (readonly)

Returns the value of attribute value



6
7
8
# File 'lib/view/formatter.rb', line 6

def value
  @value
end

Class Method Details

.as(type) ⇒ Object

Specify your own name for the formatter. By default the name of the class will be used (without any namespacing), but you can override it yourself by calling this method.

Examples:

class SomeStrangeName < View::Formatter
  as :real_name
end

View.format @foo, :as => :real_name

Parameters:

  • type (Symbol)

    The new name of the formatter



36
37
38
# File 'lib/view/formatter.rb', line 36

def self.as(type)
  @type = type
end

.inherited(formatter) ⇒ Object

When you inherit from View::Formatter, the formatters goes on the list, but in reverse order, so that newer formatters kan override older ones.



19
20
21
22
# File 'lib/view/formatter.rb', line 19

def self.inherited(formatter)
  super
  formatters.unshift(formatter)
end

.skip_blank_formatterObject

By default, blank values (nil, empty strings, etc), will override any formatter you specified. This way empty values are handled globally.

If you don't want this, you can either turn it off per formatter. Call this method to turn it off.

Examples:

class IHandleMyOwnBlank < View::Formatter
  skip_blank_formatter
  # etc...
end

See Also:



61
62
63
# File 'lib/view/formatter.rb', line 61

def self.skip_blank_formatter
  @skip_blank_formatter = true
end

.typeString

Returns the type of the formatter, either set via .as or automatically deducted from the class name.

Returns:

  • (String)

    the type of the formatter, either set via .as or automatically deducted from the class name.

See Also:



44
45
46
# File 'lib/view/formatter.rb', line 44

def self.type
  @type || name.split('::').last.underscore
end

Instance Method Details

#all_optionsObject

Returns All options, unfiltered.

Returns:

  • All options, unfiltered.

See Also:



130
131
132
# File 'lib/view/formatter.rb', line 130

def all_options
  @options
end

#formatString

This method is abstract.

Subclass and override #format to implement your own formatter.

If you didn't specify a format instance method inside specific formatters, this will raise an error.

Returns:

  • (String)

    the formatted value

Raises:

  • (NotImplementedError)


70
71
72
73
# File 'lib/view/formatter.rb', line 70

def format
  msg = "The '#{self.class.type}' formatter needs to implement the #format method."
  raise NotImplementedError.new(msg)
end

#format!String

The final result of the formatter, with the block captured if given.

If a template is given, use it to capture the block, for maximum integration with ActionView.

Returns:

  • (String)


120
121
122
123
124
125
126
# File 'lib/view/formatter.rb', line 120

def format!
  if block
    captured_value
  else
    to_s
  end
end

#optionsHash

The "safe" options that you can toss around to helper methods.

You can specify which methods are "safe" by white listing or black listing. White listing takes precedence over black listing.

To access options that are filtered out, use all_options. It's generally a good idea to black list options that you use inside your formatter.

The option :as is black listed by default.

Examples:

White listing:


class Sentence < View::Formatter
  self.allowed_options = [ :words_connector, :last_word_connector ]

  def format
    value.to_sentence(options)
  end
end

Black listing:


class Link < View::Formatter
  self.reserved_options = [ :to ]

  def format
    template.link_to(value.to_s, all_options[:to], options)
  end
end

Returns:

  • (Hash)

    filtered options

See Also:



108
109
110
111
112
# File 'lib/view/formatter.rb', line 108

def options
  default_options.merge(all_options).delete_if do |key, value|
    option_not_allowed?(key)
  end
end

#to_sObject

A hook for formatters to override so they can inject code between above the formatting, without all their inherited classes knowing about it.



136
137
138
# File 'lib/view/formatter.rb', line 136

def to_s
  format
end