Class: Hpricot::Elements

Once you‘ve matched a list of elements, you will often need to handle them as a group. Or you may want to perform the same action on each of them. Hpricot::Elements is an extension of Ruby‘s array class, with some methods added for altering elements contained in the array.

If you need to create an element array from regular elements:

  Hpricot::Elements[ele1, ele2, ele3]

Assuming that ele1, ele2 and ele3 contain element objects (Hpricot::Elem, Hpricot::Doc, etc.)

Continuing Searches

Usually the Hpricot::Elements you‘re working on comes from a search you‘ve done. Well, you can continue searching the list by using the same at and search methods you can use on plain elements.

  elements = doc.search("/div/p")
  elements = elements.search("/a[@href='http://hoodwink.d/']")
  elements = elements.at("img")

Altering Elements

When you‘re altering elements in the list, your changes will be reflected in the document you started searching from.

  doc = Hpricot("That's my <b>spoon</b>, Tyler.")
  doc.at("b").swap("<i>fork</i>")
  doc.to_html
    #=> "That's my <i>fork</i>, Tyler."

Getting More Detailed

If you can‘t find a method here that does what you need, you may need to loop through the elements and find a method in Hpricot::Container::Trav which can do what you need.

For example, you may want to search for all the H3 header tags in a document and grab all the tags underneath the header, but not inside the header. A good method for this is next_sibling:

  doc.search("h3").each do |h3|
    while ele = h3.next_sibling
      ary << ele   # stuff away all the elements under the h3
    end
  end

Most of the useful element methods are in the mixins Hpricot::Traverse and Hpricot::Container::Trav.

Constants

 %r!\[ *(?:(@)([\w\(\)-]+)|([\w\(\)-]+\(\))) *([~\!\|\*$\^=]*) *'?"?([^\]'"]*)'?"? *\]!i
 %r!(\[) *([^\]]*) *\]+!i
 %r!(:)?([a-zA-Z0-9\*_-]*)\( *[\"']?([^ \)]*?)['\"]? *\)!
 %r!(:)([a-zA-Z0-9\*_-]*)()!
 %r!([:\.#]*)([a-zA-Z0-9\*_-]+)!

Public Class methods

expand(ele1, ele2, excl=false)

Given two elements, attempt to gather an Elements array of everything between (and including) those two elements.

filter(nodes, expr, truth = true)

Public Instance methods

%(expr, &blk)

Alias for at

/(*expr,&blk)

Alias for search

add_class(class_name)

Adds the class to all matched elements.

  (doc/"p").add_class("bacon")

Now all paragraphs will have class="bacon".

after(str = nil, &blk)

Just after each element in this list, add some HTML. Pass in an HTML str, which is turned into Hpricot elements.

append(str = nil, &blk)

Add to the end of the contents inside each element in this list. Pass in an HTML str, which is turned into Hpricot elements.

at(expr, &blk)

Searches this list for the first element (or child of these elements) matching the CSS or XPath expression expr. Root is assumed to be the element scanned.

See Hpricot::Container::Trav.at for more.

attr(key, value = nil, &blk)

Gets and sets attributes on all matched elements.

Pass in a key on its own and this method will return the string value assigned to that attribute for the first elements. Or nil if the attribute isn‘t found.

  doc.search("a").attr("href")
    #=> "http://hacketyhack.net/"

Or, pass in a key and value. This will set an attribute for all matched elements.

  doc.search("p").attr("class", "basic")

You may also use a Hash to set a series of attributes:

  (doc/"a").attr(:class => "basic", :href => "http://hackety.org/")

Lastly, a block can be used to rewrite an attribute based on the element it belongs to. The block will pass in an element. Return from the block the new value of the attribute.

  records.attr("href") { |e| e['href'] + "#top" }

This example adds a top anchor to each link.

before(str = nil, &blk)

Add some HTML just previous to each element in this list. Pass in an HTML str, which is turned into Hpricot elements.

empty()

Empty the elements in this list, by removing their insides.

  doc = Hpricot("<p> We have <i>so much</i> to say.</p>")
  doc.search("i").empty
  doc.to_html
    => "<p> We have <i></i> to say.</p>"

filter(expr)

html(*string)

Alias for inner_html

html=(string)

Alias for inner_html=

innerHTML(*string)

Alias for inner_html

innerHTML=(string)

Alias for inner_html=

inner_html(*string)

Returns an HTML fragment built of the contents of each element in this list.

If a HTML string is supplied, this method acts like inner_html=.

inner_html=(string)

Replaces the contents of each element in this list. Supply an HTML string, which is loaded into Hpricot objects and inserted into every element in this list.

inner_text()

Returns an string containing the text contents of each element in this list. All HTML tags are removed.

not(expr)

prepend(str = nil, &blk)

Add to the start of the contents inside each element in this list. Pass in an HTML str, which is turned into Hpricot elements.

remove()

Remove all elements in this list from the document which contains them.

  doc = Hpricot("<html>Remove this: <b>here</b></html>")
  doc.search("b").remove
  doc.to_html
    => "<html>Remove this: </html>"

remove_attr(name)

Remove an attribute from each of the matched elements.

  (doc/"input").remove_attr("disabled")

remove_class(name = nil)

Removes a class from all matched elements.

  (doc/"span").remove_class("lightgrey")

Or, to remove all classes:

  (doc/"span").remove_class

search(*expr,&blk)

Searches this list for any elements (or children of these elements) matching the CSS or XPath expression expr. Root is assumed to be the element scanned.

See Hpricot::Container::Trav.search for more.

set(key, value = nil, &blk)

Alias for attr

text()

Alias for inner_text

to_html()

Convert this group of elements into a complete HTML fragment, returned as a string.

to_s()

Alias for to_html

wrap(str = nil, &blk)

Wraps each element in the list inside the element created by HTML str. If more than one element is found in the string, Hpricot locates the deepest spot inside the first element.

 doc.search("a[@href]").
     wrap(%{<div class="link"><div class="link_inner"></div></div>})