- Added phpdocs for constants

- Added admin permission for QBF
- Removed obsolete qbf_rewrite_form
- Implemented qbf_forms as the invoker for "hook_qbf_register"
- No longer query when just viewing the QBF form
- Now actually invokes the client module query callback
- Added qbf_query_mapper helper function to autofill default values during the module query building process

qbf.module

@@ -7,39 +7,45 @@
  *
  * @copyright 2008 Ouest Systemes Informatiques (OSInet)
  * @author Frederic G. MARAND
- * @version $Id: qbf.module,v 1.5 2008-08-27 10:45:50 marand Exp $
+ * @version $Id: qbf.module,v 1.6 2008-08-28 09:53:54 marand Exp $
  * @license CeCILL 2.0
  * @package QBF
  */
 
+/**
+ * Remove this element from the generated form
+ */
 define('QBF_LEVEL_REMOVE',           0);
-define('QBF_LEVEL_DISPLAY',          1); // Display only, don't use
+/**
+ * This element is only for display in the generated form: do not include it
+ * in the query vector.
+ */
+define('QBF_LEVEL_DISPLAY',          1);
+/**
+ * Include this element in the generated form and in the query vector, but do
+ * not mark it as required.
+ */
 define('QBF_LEVEL_OPTIONAL',         2);
+/**
+ * Include this element in the generated form and in the query vector, and
+ * mark it as required.
+ */
 define('QBF_LEVEL_REQUIRED',         3);
 
+/**
+ * The main QBF path
+ */
 define('QBF_PATH_QUERY',             'qbf/query');
 
-define('QBF_PERM_QUERY',             'use qbf search functions');
-
 /**
- * Experiment in creating a new "hook_qbf_rewrite_form()".
- *
- * @todo check whether this is redundant with hook_form_alter()
- *
- * @param array $form
- * @return array
+ * Authorize use of QBF searches
  */
-function qbf_rewrite_form($form)
-  {
-  $hookName = 'qbf_rewrite_form';
+define('QBF_PERM_QUERY',             'use QBF search functions');
+/**
+ * Authorize QBF administration
+ */
+define('QBF_PERM_ADMIN',             'administer QBF');
 
-  foreach (module_implements($hookName) as $module)
-    {
-    $function = "${module}_$hookName";
-    $form = $function($form);
-    }
-  return drupal_get_form($form);
-  }
 
 /**
  * Transform a form array for QBF.
@@ -237,17 +243,24 @@ function qbf_perm()
 /**
  * Implement hook_forms().
  *
- * @todo dynamically build the list of forms
- *
  * @return array
  */
 function qbf_forms()
   {
-  $forms['qbf_job_form'] = array
-    (
-    'callback'           => 'qbf_transform_form',
-    'callback arguments' => array('job_form'),
-    );
+  $hookName = 'qbf_register';
+
+  foreach (module_implements($hookName) as $module)
+    {
+    foreach (module_invoke($module, $hookName) as $formName)
+      {
+    	$forms["qbf_$formName"] = array
+    	  (
+    	  'callback'       => 'qbf_transform_form',
+    	  'callback arguments' => array($formName),
+    	  );
+      }
+    }
+
   return $forms;
   }
 
@@ -260,12 +273,32 @@ function qbf_forms()
  */
 function qbf_after_build($form, $form_values)
   {
+  if (empty($form['#post']))
+    {
+    return $form;
+    }
+
+  // If #post is not emtpy, we are indeed querying
   $arQuery = _qbf_extract_query($form, $form_values);
 
-  $form['food'] = array
+  /* This function is called at the end of the form building process, which
+   * means that child properties of #qbf have already been upgraded to element
+   * properties. So we look for $form['#callback'] and not
+   * $form['#qbf']['#callback']
+   */
+  if (isset($form['#callback']) && function_exists($function = $form['#callback']))
+    {
+    $results = $function($arQuery);
+    }
+  else
+    {
+    drupal_set_message(t('QBF: incorrect callback function for search'), 'error');
+    }
+  $form['qbf_query_results'] = array
     (
     '#type'    => 'markup',
-    '#value'   => "<p>" . dvr($arQuery, true) . "</p>",
+    '#value'   => $results,
+    '#weight'  => 10,
     );
   return $form;
   }
@@ -300,4 +333,42 @@ function _qbf_extract_query($form, $form_values)
     }
 
   return $ret;
+  }
+
+/**
+ * Provide an optional automatic mapping mechanism for query building.
+ *
+ * This function takes a partly built query map $arQueryMap, and a defaults
+ * array to complete it in $arDefaults, and returns a fully built query array
+ * ready to be used for querying.
+ *
+ * @param array $arQuery
+ * @param array $arDefaults
+ * @return array
+ */
+function qbf_query_mapper($arQueryMap = array(), $arDefaults = array())
+  {
+  $ret = array();
+
+  foreach ($arQueryMap as $name => $value)
+    {
+    if (!is_array($value)) // accept NULL, empty strings...
+      {
+      $value = array();
+      }
+  	$item = $value;
+
+  	foreach ($arDefaults as $defaultKey => $defaultValue)
+  	  {
+  	  if (!array_key_exists($defaultKey, $item))
+  	    {
+  	    $item[$defaultKey] = is_null($defaultValue)
+  	      ? $name
+  	      : $defaultValue;
+  	    }
+  	  // else if is already in $item, so we don't touch it
+  	  }
+  	$ret[$name] = $item;
+    }
+  return $ret;
   }