[Summary view] [Print] [Text view]

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