Class: Effigy::View

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

Overview

Accepts a template to be transformed.

For most common cases, creating a subclass makes the most sense, but this class can be used directly by passing a block to #render_html_document or #render_html_fragment.

view = Effigy::View.new view.render_html_document(template) do

view.find('h1').text('the title')

end

See Also:

Direct Known Subclasses

Rails::View

Instance Method Summary (collapse)

Instance Method Details

- (Object) add_class(selector, *class_names)

Adds the given class names to the selected elements.

Examples:

add_class('a#home', 'selected')
find('a#home').add_class('selected')

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • class_names (String) —

    a CSS class name that should be added



123
124
125
126
127
128
 
# File 'lib/effigy/view.rb', line 123

def add_class(selector, *class_names)
  select(selector).each do |element|
    class_list = ClassList.new(element)
    class_list.add class_names
  end
end

- (Object) append(selector, html_to_append)

Adds the given markup to the end of the selected elements.

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to which this HTML should be appended

  • html_to_append (String) —

    the new markup to append to the selected element. Markup is not escaped.



179
180
181
 
# File 'lib/effigy/view.rb', line 179

def append(selector, html_to_append)
  select(selector).each { |node| node.append_fragment html_to_append }
end

- (Object) attr(selector, attributes_or_attribute_name, value = nil)

Adds or updates the given attribute or attributes of the selected elements.

Examples:

attr('p', :id => 'an_id', :style => 'display: none')
attr('p', :id, 'an_id')
find('p').attr(:id, 'an_id')

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • attributes_or_attribute_name (String, Hash) —

    if a String, replaces that attribute with the given value. If a Hash, uses the keys as attribute names and values as attribute values

  • value (String) (defaults to: nil) —

    the value for the replaced attribute. Used only if attributes_or_attribute_name is a String



57
58
59
60
61
62
 
# File 'lib/effigy/view.rb', line 57

def attr(selector, attributes_or_attribute_name, value = nil)
  attributes = attributes_or_attribute_name.to_effigy_attributes(value)
  select(selector).each do |element|
    element.merge!(attributes)
  end
end

- (Selection) find(selector) Also known as: f

Selects an element or elements for chained transformation.

If given a block, the selection will be in effect during the block.

If not given a block, a Selection will be returned on which transformation methods can be called. Any methods called on the Selection will be delegated back to the view with the selector inserted into the parameter list.

Examples:

find('.post') do
  text('h1', post.title)
  text('p', post.body)
end
find('h1').text(post.title).add_class('active')

Parameters:

  • selector (String) —

    a CSS or XPath string describing the element to transform

Returns:

  • (Selection) —

    a proxy object on which transformation methods can be called



202
203
204
205
206
207
208
209
210
211
 
# File 'lib/effigy/view.rb', line 202

def find(selector)
  if block_given?
    old_context = @current_context
    @current_context = select(selector)
    yield
    @current_context = old_context
  else
    Selection.new(self, selector)
  end
end

- (Object) html(selector, inner_html)

Replaces the contents of the selected elements with live markup.

Examples:

html('p', '<b>Welcome!</b>')
find('p').html('<b>Welcome!</b>')

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • inner_html (String) —

    the new contents of the selected elements. Markup is



155
156
157
158
159
 
# File 'lib/effigy/view.rb', line 155

def html(selector, inner_html)
  select(selector).each do |node|
    node.inner_html = inner_html
  end
end

- (Object) remove(selector)

Removes the selected elements from the template.

Examples:

remove('.post')
find('.post').remove

Parameters:

  • selector (String) —

    a CSS or XPath string describing the element to transform



111
112
113
 
# File 'lib/effigy/view.rb', line 111

def remove(selector)
  select(selector).each { |element| element.unlink }
end

- (Object) remove_class(selector, *class_names)

Removes the given class names from the selected elements.

Ignores class names that are not present.

Examples:

remove_class('a#home', 'selected')
find('a#home').remove_class('selected')

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • class_names (String) —

    a CSS class name that should be removed



140
141
142
143
144
145
 
# File 'lib/effigy/view.rb', line 140

def remove_class(selector, *class_names)
  select(selector).each do |element|
    class_list = ClassList.new(element)
    class_list.remove(class_names)
  end
end

- (String) render_html_document(template) { ... }

Perform transformations on a string containing an html document.

Yields:

  • inside the given block, transformation methods such as #text and #html can be used on the template. Using a subclass, you can instead override the #transform method, which is the preferred approach.

Returns:

  • (String) —

    the transformed document



100
101
102
 
# File 'lib/effigy/view.rb', line 100

def render_html_document(template, &block)
  yield_transform_and_output(Nokogiri::HTML.parse(template), &block)
end

- (String) render_html_fragment(template) { ... }

Perform transformations on a string containing an html fragment.

Yields:

  • inside the given block, transformation methods such as #text and #html can be used on the template. Using a subclass, you can instead override the #transform method, which is the preferred approach.

Returns:

  • (String) —

    the transformed fragment



89
90
91
 
# File 'lib/effigy/view.rb', line 89

def render_html_fragment(template, &block)
  yield_transform_and_output(Nokogiri::HTML.fragment(template), &block)
end

- (Object) replace_each(selector, collection, &block)

Replaces the selected elements with a clone for each item in the collection. If multiple elements are selected, only the first element will be used for cloning. All selected elements will be removed.

Examples:

titles = %w(one two three)
find('.post').replace_each(titles) do |title|
  text('h1', title)
end

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • collection (Enumerable) —

    the items that are the base for each cloned element



77
78
79
80
 
# File 'lib/effigy/view.rb', line 77

def replace_each(selector, collection, &block)
  selected_elements = select(selector)
  ExampleElementTransformer.new(self, selected_elements).replace_each(collection, &block)
end

- (Object) replace_with(selector, html)

Replaces the selected element with live markup.

The “outer HTML” for the selected tag itself is also replaced.

Parameters:

  • selector (String) —

    a CSS or XPath string describing the element to transform

  • html (String) —

    the new markup to replace the selected element. Markup is not escaped.



169
170
171
 
# File 'lib/effigy/view.rb', line 169

def replace_with(selector, html)
  select(selector).after(html).unlink
end

- (Object) text(selector, content)

Replaces the text content of the selected elements.

Markup in the given content is escaped. Use #html if you want to replace the contents with live markup.

Examples:

text('h1', 'a title')
find('h1').text('a title')
text('p', '<b>title</b>') # <p>&lt;b&gt;title&lt;/title&gt;</p>

Parameters:

  • selector (String) —

    a CSS or XPath string describing the elements to transform

  • content (String) —

    the text that should be the new contents



38
39
40
41
42
 
# File 'lib/effigy/view.rb', line 38

def text(selector, content)
  select(selector).each do |node|
    node.content = content
  end
end

- (Object) transform

Called by render methods to perform transformations on the source template. Override this method in subclasses to perform the transformations specific to your view.

Examples:

class PostView < Effigy::View
  def initialize(post)
    @post = post
  end

  def transform
    find('.post') do
      find('h2').text(post.title)
      find('p').text(post.body)
    end
  end
end


231
232
 
# File 'lib/effigy/view.rb', line 231

def transform
end