- defined constant for permission name

- removed obsolete _qbf_view()
- improved phpdoc blocks for drupal standards
- improved inline comments and code formatting
- created the query vector builder

qbf.module

@@ -7,7 +7,7 @@
  *
  * @copyright 2008 Ouest Systemes Informatiques (OSInet)
  * @author Frederic G. MARAND
- * @version $Id: qbf.module,v 1.4 2008-08-26 16:24:07 marand Exp $
+ * @version $Id: qbf.module,v 1.5 2008-08-27 10:45:50 marand Exp $
  * @license CeCILL 2.0
  * @package QBF
  */
@@ -19,24 +19,16 @@ define('QBF_LEVEL_REQUIRED',         3);
 
 define('QBF_PATH_QUERY',             'qbf/query');
 
+define('QBF_PERM_QUERY',             'use qbf search functions');
 
-function _qbf_view($usNodeType = NULL)
-  {
-  $nodeType = filter_xss($usNodeType, array());
-
-  $arNodeTypes = node_get_types();
-  //dsm($arNodeTypes);
-  $arFuncs1 = get_defined_functions();
-  $arFuncs1 = $arFuncs1['user'];
-  $node = new stdClass();
-  $node->type = 'poll';
-  $arFuncs1 = node_forms();
-  //dsm($arFuncs1);
-  $form = node_form($node, array('qbe-key' => 'qbe-value'));
-  //dsm($form);
-  return 'foo';
-  }
-
+/**
+ * Experiment in creating a new "hook_qbf_rewrite_form()".
+ *
+ * @todo check whether this is redundant with hook_form_alter()
+ *
+ * @param array $form
+ * @return array
+ */
 function qbf_rewrite_form($form)
   {
   $hookName = 'qbf_rewrite_form';
@@ -50,7 +42,7 @@ function qbf_rewrite_form($form)
   }
 
 /**
- * Transform a form array for QBF
+ * Transform a form array for QBF.
  *
  * This function obtains the form array using Forms API, and transforms it by
  * modifying widgets to other types where needed.
@@ -97,7 +89,7 @@ function qbf_transform_form($form_id)
   }
 
 /**
- * Transform a form element for QBF
+ * Transform a form element for QBF.
  *
  * QBF-specific properties are:
  * - #qbf : array of properties
@@ -157,7 +149,7 @@ function _qbf_transform_element($key, array $element)
   $destType = array_key_exists($sourceType, $arDefaultTypeTransformations)
     ? $arDefaultTypeTransformations[$sourceType]
     : $sourceType;
-  // .. Apply type override
+  // .. Apply form-defined type override
   if (isset($element['#qbf']['#type']))
     {
     $destType = $element['#qbf']['#type'];
@@ -180,7 +172,8 @@ function _qbf_transform_element($key, array $element)
       foreach (element_properties($element) as $propertyName)
         {
         // Apply killer properties first to avoid useless work
-        if (array_key_exists($propertyName, $arKillerProperties) && ($element[$propertyName] = $arKillerProperties[$propertyName]))
+        if (array_key_exists($propertyName, $arKillerProperties)
+          && ($element[$propertyName] = $arKillerProperties[$propertyName]))
           {
           $ret = NULL;
           break;
@@ -196,7 +189,7 @@ function _qbf_transform_element($key, array $element)
           $ret[$propertyName] = $element[$propertyName];
           }
 
-        // And apply form-defined overrides
+        // And apply form-defined property overrides
         if ($propertyName == '#qbf')
           {
           foreach ($element[$propertyName] as $overrideName => $overrideValue)
@@ -206,6 +199,7 @@ function _qbf_transform_element($key, array $element)
           }
         }
 
+      // Recursively transform children
       foreach (element_children($element) as $childName)
         {
         $child = _qbf_transform_element($childName, $element[$childName]);
@@ -225,14 +219,23 @@ function _qbf_transform_element($key, array $element)
   return $ret;
   }
 
+/**
+ * Implement hook_perm().
+ *
+ * @return array
+ */
 function qbf_perm()
   {
-  $ret = array('use qbf search functions');
+  $ret = array
+    (
+    QBF_PERM_QUERY,
+    );
+
   return $ret;
   }
 
 /**
- * Implement hook_forms
+ * Implement hook_forms().
  *
  * @todo dynamically build the list of forms
  *
@@ -248,22 +251,53 @@ function qbf_forms()
   return $forms;
   }
 
+/**
+ * Insert the query results at the bottom of the query form.
+ *
+ * @param array $form
+ * @param array $form_values
+ * @return array
+ */
 function qbf_after_build($form, $form_values)
   {
-  $arQuery = array();
-  dsm($form_values);
-  foreach (element_children($form) as $childName)
-    {
-    if ($form[$childName]['#qbf']['#level'] > QBF_LEVEL_REMOVE)
-      {
-      $arQuery[] = $childName . '=' . $form[$childName]['#value'];
-      }
-    }
-  $query = implode(', ', $arQuery);
+  $arQuery = _qbf_extract_query($form, $form_values);
+
   $form['food'] = array
     (
     '#type'    => 'markup',
-    '#value'   => "<p>Requête sur $query</p>",
+    '#value'   => "<p>" . dvr($arQuery, true) . "</p>",
     );
   return $form;
   }
+
+/**
+ * Recursively build a query array from the form and its values
+ *
+ * In the current version, element names are supposed to be unique, even at
+ * different levels in the tree.
+ *
+ * @param array $form
+ * @param array $form_values
+ */
+function _qbf_extract_query($form, $form_values)
+  {
+  $name = $form['#parents'][0];
+  // Elements which are removed or display-only have no place in the query
+  if (array_key_exists('#qbf', $form) && array_key_exists('#level', $form['#qbf'])
+    && $form['#qbf']['#level'] >= QBF_LEVEL_OPTIONAL)
+    {
+    $ret = array($name => $form_values[$name]);
+    }
+  else
+    {
+    $ret = array();
+    }
+
+  // QBF level is not inherited, so this loop is outside the "if" above
+  foreach (element_children($form) as $childName)
+    {
+  	$ret += _qbf_extract_query($form[$childName], $form_values);
+    }
+
+  return $ret;
+  }