Provides an easy support for querying elements in many Mechanize modules.

This module is not primarily designed to be used by cliente code, instead you should use indirectly throught Mechanize.Page.search/2 and Mechanize.Page.filter_out/2. Many other functions that accept Mechanize.Query.t() also uses this module under the hood. Therefore it's important to understand how this module works to unlock all capabilities in functions that use queries.

Examples

For example, Mechanize.Page.click_link!/2 is one function of Mechanize API which accepts a query as second parameter. You can click in a link based on it's attributes:

alias Mechanize.Page

Page.click_link!(page, href: "/home/about")

When you call Mechanize.Page.click_link!/2, another call to Mechanize.Query.elements_with/3 is made under the hood to fetch all links with given [href: "/home/about"] query and then Mechanize "clicks" on the first link.

You can also query elements by its inner text, which is the visible text in case of text links:

Page.click_link!(page, text: "About")

Or you can use a shorter approach for doing the same:

Page.click_link!(page, "About")

Query powered functions also accepts regular expressions:

Page.click_link!(page, href: ~r/about/)

You can combine different types of queries at once. The following example returns a list of links by its href, title attributes and inner text.

Page.links_with(page, href: "/home/about", title: "About page", text: "About page")

Use boolean to query if an element attribute exists. In example below, we fetch all checked and unchecked checkboxes from a given form:

alias Mechanize.Form

Form.checkboxes_with(form, checked: true) # => checkboxes with checked attribute present
Form.checkboxes_with(form, checked: false) # => checkboxes with checked attribute not present

In case of elements that have a logical order, which is the case of select element in a html form, you can query it by its index. Note that this index is a zero-based index. In the example below, we select the first option from a select list with attribute name="selectlist1":

Form.select(form, name: "selectlist1", option: 0)

Finally, you can also query elements with different attribute values. In the example below, Mechanize "clicks" on the first link found with href equals to "/company" or "/about":

Page.click_link!(page, href: ["/company", "/about"])

Page fragments

Many queries can work both on Mechanize.Page or in page fragments. A page fragment is nothing but a list of data which its type implements Mechanize.Page.Elementable protocol.

For example, the function Mechanize.Page.search/2, which is also powered by this module, returns a page fragment. This mechanism enable client code to chain queries like in the example:

  page
  |> Page.search(".planetmap")
  |> Page.click_link!("Sun")

When you chain functions like that, Mechanize.Page.click_link!/2 will only work on page fragment returned by Mechanize.Page.search/2 function. That means Mechanize will click on a link with attribute alt="Sun" only if its child of a .planetmap, ignoring all others that are not child.

But there's another use case. You can also click on a link if the link is the page fragment itself, like in example below:

  page
  |> Page.search(".planetmap a")
  |> Page.click_link!("Sun")