[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @file form_builder.api.inc
   5   * Universally used API functions within the Form builder module.
   6   */
   7  
   8  /**
   9   * Get a list of all properties that are supported within a form type.
  10   */
  11  function form_builder_get_properties($form_type, $reset = FALSE) {
  12    static $properties = array();
  13  
  14    if ($reset) {
  15      $properties = array();
  16    }
  17  
  18    if (!isset($properties[$form_type])) {
  19      // Get the list of all properties for all elements.
  20      foreach (module_implements('form_builder_properties') as $module) {
  21        $properties = array_merge($properties, module_invoke($module, 'form_builder_properties', $form_type));
  22      }
  23      drupal_alter('form_builder_properties', $properties, $form_type);
  24    }
  25  
  26    return $properties;
  27  }
  28  
  29  /**
  30   * Get a list of all properties that are supported by a particular form type.
  31   */
  32  function form_builder_get_form_type($form_type = NULL, $reset = FALSE) {
  33    static $types;
  34  
  35    if (!isset($types) || $reset) {
  36      $types = array();
  37      // Get the list of all properties for all elements.
  38      $types = module_invoke_all('form_builder_types');
  39  
  40      // Add default values for undefined properties.
  41      foreach ($types as $type_key => &$type) {
  42        $groups = module_invoke_all('form_builder_palette_groups', $type_key);
  43  
  44        foreach ($type as $field_key => &$field) {
  45          $field['unique'] = isset($field['unique']) && $field['unique'];
  46          $field['configurable'] = isset($field['configurable']) ? $field['configurable'] : TRUE;
  47          $field['removable'] = isset($field['removable']) ? $field['removable'] : TRUE;
  48          $field['addable'] = isset($field['addable']) ? $field['addable'] : $field['removable'] && isset($field['default']);
  49          $field['palette_group'] = isset($field['palette_group']) && isset($groups[$field['palette_group']]) ? $field['palette_group'] : 'default';
  50          $field['properties'] = isset($field['properties']) ? $field['properties'] : array();
  51  
  52          // All fields must support weight.
  53          if (!in_array('weight', $field['properties'])) {
  54            $field['properties'][] = 'weight';
  55          }
  56  
  57          // Update the default elements with some defaults.
  58          // Note that if a field is not removable, it doesn't have a default.
  59          if ($field['addable']) {
  60            if ($field['unique']) {
  61              $field['default']['#form_builder']['element_id'] = $field_key;
  62              $field['default']['#form_builder']['element_type'] = $field_key;
  63            }
  64            elseif (!isset($field['default']['#form_builder']['element_type'])) {
  65              $field['default']['#form_builder']['element_type'] = $field_key;
  66            }
  67          }
  68        }
  69  
  70        // Sort fields by weight and title.
  71        uasort($type, '_form_builder_sort');
  72      }
  73  
  74      drupal_alter('form_builder_types', $types);
  75    }
  76  
  77    return isset($form_type) ? $types[$form_type] : $types;
  78  }
  79  
  80  /**
  81   * Given an element type, return properties that are supported by Form builder.
  82   *
  83   * @param $form_type
  84   *   The type of form being edited (profile, node, webform, etc.)
  85   * @param $element_type
  86   *   A the #type property of a FAPI element.
  87   * @param
  88   *   An associative array of properties supported for editing, keyed by
  89   *   the property name and containing an array of the form, submit, and
  90   *   validate functions (if any).
  91   */
  92  function form_builder_get_element_properties($form_type, $element_type) {
  93    // Get the list of all properties for this type.
  94    $properties = form_builder_get_properties($form_type);
  95  
  96    // Get the list of supported properties per field in this form type.
  97    $form_type = form_builder_get_form_type($form_type);
  98  
  99    $element_properties = array();
 100    if (isset($form_type[$element_type]['properties'])) {
 101      foreach ($form_type[$element_type]['properties'] as $property) {
 102        if (isset($properties[$property])) {
 103          $element_properties[$property] = $properties[$property];
 104        }
 105      }
 106    }
 107  
 108    return $element_properties;
 109  }
 110  
 111  /**
 112   * Get a list of properties that are supported in any way by an element.
 113   *
 114   * This returns a list of all supported properties within an element, even
 115   * if some of those properties do not have an interface for editing or are
 116   * only used internally by the module providing the form type this element
 117   * is being saved in.
 118   *
 119   * @param $form_type
 120   *   The type of form being edited (profile, node, webform, etc.)
 121   * @param $element
 122   *   A standard FAPI element whose properties are being checked.
 123   * @return
 124   *   A non-indexed list of properties that may be saved for this element.
 125   * */
 126  function form_builder_get_saveable_properties($form_type, $element) {
 127    // Get the list of supported properties on each element.
 128    $form_type = form_builder_get_form_type($form_type);
 129  
 130    $saveable = array();
 131    if (isset($form_type[$element['#form_builder']['element_type']]['properties'])) {
 132      $saveable = $form_type[$element['#form_builder']['element_type']]['properties'];
 133    }
 134  
 135    return $saveable;
 136  }
 137  
 138  /**
 139   * Function to retrieve a single element within a form structure.
 140   *
 141   * If needing to retreive multiple elements at once, use
 142   * form_builder_get_elements().
 143   *
 144   * @param $form
 145   *   A complete hierarchical FAPI structure.
 146   * @param $element_id
 147   *   The unique identifier for an element that is to be retrieved.
 148   * @return
 149   *   A single Form API element array.
 150   *
 151   * @see form_builder_get_elements().
 152   */
 153  function form_builder_get_element(&$form, $element_id) {
 154    $elements = form_builder_get_elements($form, array($element_id));
 155    return isset($elements[$element_id]) ? $elements[$element_id] : FALSE;
 156  }
 157  
 158  /**
 159   * Recursive function to retrieve multiple elements within a form structure.
 160   *
 161   * @param $form
 162   *   A complete hierarchical FAPI structure.
 163   * @param $element_ids
 164   *   An array of unique identifiers for elements that are to be retreived. These
 165   *   identifiers match against the special property
 166   *   "#form_builder['element_id']", which is not available in normal FAPI
 167   *   structures. It must be added by the respective module that is providing
 168   *   support for a certain field type.
 169   *
 170   *   For example, CCK provides a unique identifier for each field such as
 171   *   "field_my_name". This field name must be added to the form array as
 172   *   #form_builder['element_id'] = 'field_my_name' in CCK's implementation of
 173   *   hook_form_builder_load().
 174   * @return
 175   *   A single Form API element array.
 176   */
 177  function form_builder_get_elements(&$form, $element_ids) {
 178    $elements = array();
 179    foreach (element_children($form) as $key) {
 180      if (isset($form[$key]['#form_builder']['element_id']) && in_array($form[$key]['#form_builder']['element_id'], $element_ids)) {
 181        $elements[$form[$key]['#form_builder']['element_id']] = $form[$key];
 182      }
 183      $additional_elements = form_builder_get_elements($form[$key], $element_ids);
 184      $elements = array_merge($elements, $additional_elements);
 185    }
 186    return $elements;
 187  }
 188  
 189  /**
 190   * Recursive function to set an element within a form structure.
 191   *
 192   * @return
 193   *   TRUE if an element was updated, FALSE if it was not found.
 194   */
 195  function form_builder_set_element(&$form, $element, &$entire_form = NULL, $parent_id = FORM_BUILDER_ROOT) {
 196    $return = FALSE;
 197  
 198    if (!isset($entire_form)) {
 199      $entire_form = &$form;
 200    }
 201  
 202    // Add new elements into the current parent.
 203    if (isset($element['#form_builder']['is_new']) && strcmp($element['#form_builder']['parent_id'], $parent_id) == 0) {
 204      unset($element['#form_builder']['is_new']);
 205      unset($element['#form_builder']['parent_id']);
 206      $new_key = $element['#key'];
 207      $form[$new_key] = $element;
 208      return TRUE;
 209    }
 210  
 211    foreach (element_children($form) as $key) {
 212      // Update an existing element if it lives in the current parent.
 213      if (isset($form[$key]['#form_builder']['element_id']) && $form[$key]['#form_builder']['element_id'] == $element['#form_builder']['element_id']) {
 214  
 215        // If the parent has changed, re-parent the element to a new fieldset.
 216        if (isset($element['#form_builder']['parent_id']) && strcmp($element['#form_builder']['parent_id'], $parent_id) != 0) {
 217          // Remove the current element from the form.
 218          unset($form[$key]);
 219          // Recurse again through the entire form to insert into the new position.
 220          $element['#form_builder']['is_new'] = TRUE;
 221          $return = form_builder_set_element($entire_form, $element);
 222        }
 223        // Handle key changes and replace the existing element in place.
 224        elseif (isset($element['#key']) && $key != $element['#key']) {
 225          $new_key = $element['#key'];
 226          $index = array_search($key, array_keys($form));
 227          $before = array_slice($form, 0, $index, TRUE);
 228          $after = array_slice($form, $index + 1, NULL, TRUE);
 229          $form = $before + array($new_key => $element) + $after;
 230          unset($form[$key]);
 231          $return = TRUE;
 232        }
 233        // Or, most common case scenario, just update the element, no key changes.
 234        else {
 235          $form[$key] = $element;
 236          $return = TRUE;
 237        }
 238      }
 239  
 240      // Recurse into this element to look for the target element.
 241      if (!$return && isset($form[$key]['#form_builder'])) {
 242        $return = form_builder_set_element($form[$key], $element, $entire_form, $form[$key]['#form_builder']['element_id']);
 243      }
 244  
 245      if ($return) {
 246        return $return;
 247      }
 248    }
 249  
 250    return $return;
 251  }
 252  
 253  /**
 254   * Recursive function to unset an element within a form structure.
 255   */
 256  function form_builder_unset_element(&$form, $element_id) {
 257    foreach (element_children($form) as $key) {
 258      if (isset($form[$key]['#form_builder']['element_id']) && $form[$key]['#form_builder']['element_id'] == $element_id) {
 259        unset($form[$key]);
 260        break;
 261      }
 262      form_builder_unset_element($form[$key], $element_id);
 263    }
 264  }
 265  
 266  /**
 267   * Recursive function to check if an element exists at all within a form.
 268   */
 269  function form_builder_get_element_ids($form) {
 270    $element_ids = array();
 271    foreach (element_children($form) as $key) {
 272      if (isset($form[$key]['#form_builder']['element_id'])) {
 273        $element_ids[] = $form[$key]['#form_builder']['element_id'];
 274      }
 275      $additional_ids = form_builder_get_element_ids($form[$key]);
 276      $element_ids = array_merge($element_ids, $additional_ids);
 277    }
 278  
 279    return $element_ids;
 280  }
 281  
 282  /**
 283   * Loader function to retrieve a form builder configuration array.
 284   *
 285   * @param $form_type
 286   *   The type of form being edited. Usually the name of the providing module.
 287   * @param $form_id
 288   *   The unique identifier for the form being edited with the type.
 289   */
 290  function form_builder_load_form($form_type, $form_id) {
 291    $form = module_invoke_all('form_builder_load', $form_type, $form_id);
 292    drupal_alter('form_builder_load', $form, $form_type, $form_id);
 293  
 294    // Convert the form array keys to #key properties for editing.
 295    return form_builder_add_default_properties($form, $form_type);
 296  }
 297  
 298  /**
 299   * Execute the save methods for a form array.
 300   */
 301  function form_builder_save_form(&$form, $form_type, $form_id) {
 302    module_invoke_all('form_builder_save', $form, $form_type, $form_id);
 303    form_builder_cache_delete($form_type, $form_id);
 304  }
 305  
 306  /**
 307   * Helper function to add default #form_builder properties to a form.
 308   */
 309  function form_builder_add_default_properties($form, $form_type, $key = NULL, $parent_id = FORM_BUILDER_ROOT) {
 310    $form_type_fields = form_builder_get_form_type($form_type);
 311  
 312    // Add properties to this element.
 313    if (isset($form['#form_builder']['element_id'])) {
 314      $element_id = $form['#form_builder']['element_id'];
 315  
 316      // Add a #key property.
 317      $form['#key'] = isset($form['#key']) ? $form['#key'] : $key;
 318  
 319      // Add a #form_builder['parent_id'] property.
 320      $form['#form_builder']['parent_id'] = $parent_id;
 321      $parent_id = $element_id;
 322  
 323      // Set defaults based on the form type.
 324      if (isset($form_type_fields[$element_id]) && $form_type_fields[$element_id]['unique']) {
 325        $form['#form_builder']['unique'] = TRUE;
 326        $form['#form_builder']['element_type'] = isset($form['#form_builder']['element_type']) ? $form['#form_builder']['element_type'] : $element_id;
 327        $settings = $form_type_fields[$element_id];
 328      }
 329      else {
 330        $form['#form_builder']['element_type'] = isset($form['#form_builder']['element_type']) ? $form['#form_builder']['element_type'] : $form['#type'];
 331        if (isset($form_type_fields[$form['#form_builder']['element_type']])) {
 332          $settings = $form_type_fields[$form['#form_builder']['element_type']];
 333        }
 334        else {
 335          // If the type cannot be found, prevent editing of this field.
 336          unset($form['#form_builder']);
 337          return;
 338        }
 339      }
 340  
 341      // Set defaults for configurable and removable.
 342      if (!isset($form['#form_builder']['configurable'])) {
 343        $form['#form_builder']['configurable'] = isset($settings['configurable']) ? $settings['configurable'] : TRUE;
 344      }
 345      if (!isset($form['#form_builder']['removable'])) {
 346        $form['#form_builder']['removable'] = isset($settings['removable']) ? $settings['removable'] : TRUE;
 347      }
 348    }
 349  
 350    // Recurse into sub-elements.
 351    foreach (element_children($form) as $key) {
 352      if (isset($form[$key]['#form_builder']['element_id'])) {
 353        $form[$key] = form_builder_add_default_properties($form[$key], $form_type, $key, $parent_id);
 354      }
 355    }
 356  
 357    return $form;
 358  }
 359  
 360  /**
 361   * Helper function to sort elements by 'weight' and 'title'.
 362   */
 363  function _form_builder_sort($a, $b) {
 364    $a_weight = (is_array($a) && isset($a['weight'])) ? $a['weight'] : 0;
 365    $b_weight = (is_array($b) && isset($b['weight'])) ? $b['weight'] : 0;
 366    if ($a_weight == $b_weight) {
 367      if (!isset($b['title'])) {
 368        return -1;
 369      }
 370      if (!isset($a['title'])) {
 371        return 1;
 372      }
 373      return strcasecmp($a['title'], $b['title']);
 374    }
 375    return ($a_weight < $b_weight) ? -1 : 1;
 376  }