Hackery, Math & Design

Steven Wittens i

fQuery

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:

CSSForm API
Tag namesField types
e.g. textfield
Class namesBinary field attributes
e.g. .collapsible
IDsField array keys
e.g. 'status'
HTML attributesField properties
e.g. #size
HTML attributes
e.g. class.

Here are some example queries:

fieldsetAll fieldsets
[#type=fieldset]All fieldsets (alternative)
#statusAll elements with array key name 'status'
.resizableAll 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-childAll textfields that are at the beginning of a fieldset
textfield + textfieldAll textfields that come right after another textfield.
textfield ~ textfieldAll 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
Drupal  FAPI  fQuery  jQuery
This article contains graphics made with WebGL, which your browser does not seem to support.
Try Google Chrome or Mozilla Firefox. ×