fQuery

fQuery is a Drupal module to help you deal with Form API arrays. Inspired by the jQuery library, it lets you find form elements using a simple and intuitive selector scheme, based on CSS.

Download

fQuery is maintained in the Drupal.org Contributions repository. Downloads are on the fQuery project page.

To check out the included demo, install the module, copy example.php to the site root and visit it with your browser.

Usage

When fQuery is installed and enabled, use the f(); function to make queries. For example, selecting all collapsible fieldsets in a form is done using:

<?php
$query = f("fieldset.collapsible", $form);
foreach ($query as &$element) {
...
}
?>

Any module that uses fQuery should indicate its dependency in its .info file.

Overview

The following table summarizes how fQuery maps CSS concepts to Form API:

CSS	Form API
Tag names	Field types e.g. textfield
Class names	Binary field attributes e.g. .collapsible
IDs	Field array keys e.g. 'status'
HTML attributes	Field properties e.g. #size HTML attributes e.g. class.

Here are some example queries:

fieldset	All fieldsets
[#type=fieldset]	All fieldsets (alternative)
#status	All elements with array key name 'status'
.resizable	All items with '#resizable' set to true.
[#resizable]	All items with '#resizable' set to a non-empty value when cast to string.
[#title=Authored by]	All elements whose title is 'Authored by'
[#description*=http://drupal.org/]	All elements who link to drupal.org in their description.
[class~=ponies]	All elements whose #attributes => ('class' => '...') property contains the word ponies
fieldset:not(.collapsible)	All fieldsets which aren't collapsible (:not cannot be nested)
fieldset > textfield:first-child	All textfields that are at the beginning of a fieldset
textfield + textfield	All textfields that come right after another textfield.
textfield ~ textfield	All textfields that are preceded by at least one other textfield (siblings only).

Supported operators

These operators can be combined into complex selectors, according to the CSS syntax. See the examples above.

Note: All the [...] operators can be applied both with and without '#' in the attribute name to select Form API properties (like '#required' or '#size') instead of HTML attributes (like 'class' or 'title').

*

Any element

foo

An element of type foo

[foo]

An element with a "foo" HTML attribute

[foo="bar"]

An element whose "foo" HTML attribute value is exactly equal to "bar"

[foo~="bar"]

An element whose "foo" HTML attribute value is a list of space-separated values, one of which is exactly equal to "bar"

[foo^="bar"]

An element whose "foo" HTML attribute value begins exactly with the string "bar"

[foo$="bar"]

An element whose "foo" HTML attribute value ends exactly with the string "bar"

[foo*="bar"]

An element whose "foo" HTML attribute value contains the substring "bar"

:nth-child(n)

An element, the n-th child of its parent

:nth-last-child(n)

An element, the n-th child of its parent, counting from the last one

:first-child

An element, first child of its parent

:last-child

An element, last child of its parent

:only-child

An element, only child of its parent

:empty

An element that has no children

.foo

An element whose binary property "#foo" is true

#foo

An element with array key equal to "foo"

:not(s)

An element that does not match simple selector s (the operators below are not allowed)

E F

An F element descendant of an E element

E > F

An F element child of an E element

E ~ F

An F element preceded by an E element

E + F

An F element immediately preceded by an E element

fQuery Sneak Preview

Update: fQuery has been released.

Here's a sneak preview of something I've been working on since DrupalCon Brussels...

I've noticed that most hook_form_alter() uses need to look for certain elements in the $form array. For example, you want to make all resizable textareas fixed height. This means you have to iterate over $form and do recursion, find the matching elements and change them. That sucks.

What if you could just find all elements with certain properties with one line of code, and do stuff with them? Doesn't this sound at all familiar?

Enter fQuery. In a hook_form_alter(), you could do:

<?php
$query = f('textarea.resizable', $form);
foreach ($query as &$element) {
  $element['#resizable'] = FALSE;
}
?>

Neat huh?