FormQuery

Summary

This module provides developers with a tool to search, analyze and modify form arrays.
For a full list of implemented plugins see plugins/plugins.inc.
For a full list of implemented selectors (besides #type and array) see plugins/selectors.inc

Roadmap

• Add description and arguments to plugin definition arrays
• Implement ->default() and :changed
• Generate help page from plugin definitions
• Implement complex array merge operations (prepend, append, replace, delete)
• Add tests for array merging
• Implement ->prop()
• Implement ->val()
• Implement ->attr()
• Implement structure manipulations
• Add tests for structure changes
• Implement callback helpers (bind, unbind?)
• Create API file
• Collect real world examples
• Write documentation
• Apply for full project
• Extend string selector capabilities

Examples

Finding and filtering

      // Initialization
      $qform = fq($form);

      // Ways to retrieve the "Revision log message" textarea on a node form

      // A: Find
      $log_msg = $qform->find('textarea:name(log)');

      // B: Find + Filter
      $log_msg = $qform->find('textarea')->filter(':name(log)');

      // C: Find, Filter and a detour (introducing ->assign())
      $log_msg = $qform->find(':name(revision_information)')->assign($revision_info)->find(':name(log)');

      // Bonus: Returning the parent element
      $revision_info = $log_msg->parent();

      // Fetching the elements

      // A: Returning the first element (note the assignment by reference)
      $textarea = & $log_msg->get(0);
      $textarea['#title'] = 'Sweet!';

      // B: Returning all elements
      $textareas = $log_msg->get();
      $textareas[0]['#title'] = 'Sweeter!';

Exporting

      // Initialization
      $qform = fq($form);

      // Exporting submit buttons on a node form

      // Temporarily changing the output callback to drupal_debug(). This could
      // also be "var_dump", "dpm" or any function taking a single argument.
      formquery_output_func('drupal_debug', TRUE);

      // A: Exporting full element arrays
      $qform->find('submit')->export();

      // B: Exporting only paths containing "#value" by providing the "filter" option
      $qform->find('submit')->export('form', FALSE, array('filter' => '#value'));

      // C: Exporting relative paths by passing TRUE for the $relative argument
      $qform->find('submit:name(preview)')->export('preview_button', TRUE);

The output of example A:

$form['actions']['submit']['#type'] = 'submit';
$form['actions']['submit']['#access'] = TRUE;
$form['actions']['submit']['#value'] = 'Save';
$form['actions']['submit']['#weight'] = 5;
$form['actions']['submit']['#submit'][0] = 'node_form_submit';
$form['actions']['submit']['#fqid'] = 21;
$form['actions']['preview']['#access'] = TRUE;
$form['actions']['preview']['#type'] = 'submit';
$form['actions']['preview']['#value'] = 'Preview';
$form['actions']['preview']['#weight'] = 10;
$form['actions']['preview']['#submit'][0] = 'node_form_build_preview';
$form['actions']['preview']['#fqid'] = 22;

The output of example B:

$form['actions']['submit']['#value'] = 'Save';
$form['actions']['preview']['#value'] = 'Preview';

The output of example C:

$preview_button['#access'] = TRUE;
$preview_button['#type'] = 'submit';
$preview_button['#value'] = 'Preview';
$preview_button['#weight'] = 10;
$preview_button['#submit'][0] = 'node_form_build_preview';
$preview_button['#fqid'] = 22;