[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: form_builder_hooks.php,v 1.5 2009/06/19 20:48:33 quicksketch Exp $
   3  
   4  /**
   5   * @addtogroup hooks
   6   * @{
   7   */
   8  
   9  /**
  10   * @file
  11   * These are the hooks that are invoked by Form Builder.
  12   */
  13  
  14  /**
  15   * Define the fields and properties supported by a form type.
  16   *
  17   * All modules that wish to create an configurable form need implement this hook. It
  18   * defines to Form Builder what types of fields the implementing module knows
  19   * how to modify. Within each field that is modifiable, the properties that
  20   * may be changed are also listed.
  21   *
  22   * @return
  23   *   An array of form types that this module may edit. Within each form type,
  24   *   a list of fields that can be edited. Each field contains the following
  25   *   properties:
  26   *   - title: The name of the field type that is displayed in the new fields
  27   *     block.
  28   *   - properties: An array of properties that are configurable. Configuration
  29   *     of these properties is defined by hook_form_builder_properties().
  30   *   - default: A complete sample form element that will be used when a new
  31   *     element of this type is added to the form. Further modification of this
  32   *     default element may be done in hook_form_builder_element_alter().
  33   */
  34  function hook_form_builder_types() {
  35    $fields = array();
  36  
  37    // The #type property of the field is used as the key.
  38    $fields['textfield'] = array(
  39      'title' => t('Textfield'),
  40      // Properties that may be edited on this field type.
  41      'properties' => array(
  42        'title',
  43        'description',
  44        'field_prefix',
  45        'field_suffix',
  46        'default_value',
  47        'required',
  48        'size',
  49      ),
  50      // A complete default form element used when a new field of this type
  51      // is added to a form.
  52      'default' => array(
  53        '#title' => t('New textfield'),
  54        '#type' => 'textfield',
  55      ),
  56      // If needing only a single field of this type in an entire form, specify
  57      // the "unique" property. The form element will be remove from the new
  58      // field pallette when added. If the field is deleted from the form, the
  59      // field option will reappear in the new field block.
  60      // 'unique' => TRUE,
  61    );
  62  
  63    // Return the array of supported fields, with a key for the form type that
  64    // these fields apply to.
  65    return array(
  66      'node' => $fields,
  67    );
  68  }
  69  
  70  /**
  71   * Defined globally available Form API properties.
  72   *
  73   * The hook_form_builder_properties() hook allows modules to define properties
  74   * that are configurable within form elements. Properties defined by any module may be
  75   * used inside of any form element, so unique property names are advised.
  76   *
  77   * Typically, this hook only needs to implemented if your module also has an
  78   * implementation of hook_elements(). In which case you would implement
  79   * hook_form_builder_properties to inform Form Builder of the new properties
  80   * that are configurable.
  81   *
  82   * @param $form_type
  83   *   The type of form for which these properties apply. You may choose to ignore
  84   *   the value of this parameter if your properties apply globally to all forms.
  85   *
  86   * @return
  87   *   An array of properties, each containing the name of a function for a form
  88   *   to editing that property. If needed additional submit and validate
  89   *   handlers may also be added.
  90   *
  91   * @ingroup form_builder
  92   */
  93  function hook_form_builder_properties($form_type) {
  94    return array(
  95      'title' => array(
  96        'form' => 'form_builder_property_title_form',
  97      ),
  98      'description' => array(
  99        'form' => 'form_builder_property_description_form',
 100      ),
 101      'options' => array(
 102        'form' => 'form_builder_property_options_form',
 103        'submit' => array('form_builder_property_options_form_submit'),
 104      ),
 105    );
 106  }
 107  
 108  /**
 109   * Define globally available #element_validate functions.
 110   *
 111   * @param $form_type
 112   *   The form type for which this validator will be available. You may
 113   *   optionally check this value if you'd like to limit this validator to only
 114   *   certain form types.
 115   */
 116  function hook_form_builder_validators($form_type) {
 117    return array(
 118      'form_validate_integer' => array(
 119        'form' => 'form_builder_validate_integer',
 120      ),
 121      'form_validate_decimal' => array(
 122        'form' => 'form_builder_validate_decimal',
 123      ),
 124      'form_validate_email' => array(
 125        'form' => 'form_builder_validate_email',
 126      ),
 127      'form_validate_url' => array(
 128        'form' => 'form_builder_validate_url',
 129      ),
 130    );
 131  }
 132  
 133  /**
 134   * Designate groups of properties. Displayed as tabs when editing a field.
 135   *
 136   * Most properties will fall into one of the predefined categories created by
 137   * Form Builder, but it may be desired that some properties be split into
 138   * entirely different groups to separate them from other property options.
 139   *
 140   * Form Builder provides the following groups by default:
 141   *  - default: The "Properties" tab, used if no group is specified.
 142   *  - hidden: Not displayed at all unless JavaScript is disabled.
 143   *  - display: The "Display" tab. Use for properties that are purely cosmetic.
 144   *  - options: The "Options" tab. Typically used for select list, radio,
 145   *    or checkbox options.
 146   *  - validation: The "Validation" tab. Use for properties or configuration
 147   *    that enables validation functions on the element.
 148   *
 149   * @param $form_type
 150   *   The form type for which this group will be available. You may optionally
 151   *   check this value if you'd like to limit this group to only certain form
 152   *   types.
 153   *
 154   * @return
 155   *   An array of property groups, keyed by the value used in the
 156   *   #form_builder['property_group'] property.
 157   *
 158   * @see hook_form_builder_load()
 159   *
 160   * @ingroup form_builder
 161   */
 162  function hook_form_builder_property_groups($form_type) {
 163    return array(
 164      'my_group' => array(
 165        // Low weight values will appear as first tabs.
 166        'weight' => 0,
 167        // The title will be used as the tab title.
 168        'title' => t('My group'),
 169      ),
 170      'my_hidden_group' => array(
 171        'weight' => 100,
 172        'title' => t('Advanced'),
 173         // When JavaScript is enabled, collapsed groups will not be rendered.
 174         // This group will only be displayed when JavaScript is disabled.
 175        'collapsible' => TRUE,
 176        'collapsed' => TRUE,
 177      ),
 178    );
 179  }
 180  
 181  /**
 182   * Modify an individual element before it is displayed in the form preview.
 183   *
 184   * This function is typically used to cleanup a form element just before it
 185   * is rendered. The most important purpose of this function is to filter out
 186   * dangerous markup from unfiltered properties, such as #description.
 187   * Properties like #title and #options are filtered by the Form API.
 188   */
 189  function hook_form_builder_preview_alter(&$element, $form_type, $form_id) {
 190    if ($form_type == 'node') {
 191      if (isset($element['#description'])) {
 192        $element['#description'] = filter_xss($element['#description']);
 193      }
 194    }
 195  }
 196  
 197  /**
 198   * Modify an individual element before it is added to a new form.
 199   *
 200   * This function may be helpful for setting a new element #key,
 201   * #form_builder['element_id'], or adjusting access in the
 202   * #form_builder['configurable'] and #form_builder['removable'] properties.
 203   */
 204  function hook_form_builder_add_element_alter(&$element, $form_type, $form_id) {
 205    if ($form_type == 'node') {
 206      $element['#key'] = 'something';
 207    }
 208  }
 209  
 210  /**
 211   * Take a Form API array and save settings for changed elements.
 212   *
 213   * @param $form_type
 214   *   The type of form being loaded.
 215   * @param $form_id
 216   *   The unique identifier for the form being edited.
 217   */
 218  function hook_form_builder_load($form_type, $form_id) {
 219    if ($form_type == 'node') {
 220      $node = (object) array(
 221        'type' => preg_replace('/_node_form/', '', $form_id),
 222      );
 223  
 224      // Load the form, usually by calling it's function directly.
 225      $form = node_form(array(), $node);
 226  
 227      // Allow other modules to extend the form.
 228      drupal_alter('form', $form, array(), $form_id);
 229  
 230      // Loop through the form and add #form_builder properties to each element
 231      // that is configurable.
 232      foreach (element_children($form) as $key) {
 233        $form[$key]['#form_builder'] = array(
 234          'configurable' => TRUE,
 235          'removable' => TRUE,
 236          // If unique, when this element is deleted, a new one will appear in the
 237          // new field pallette.
 238          //'unique' => TRUE,
 239        );
 240      }
 241  
 242      return $form;
 243    }
 244  }
 245  
 246  /**
 247   * Take a form builder array and save changes permanently.
 248   */
 249  function hook_form_builder_save(&$form, $form_type, $form_id) {
 250    if ($form_type == 'node') {
 251      foreach (element_children($form) as $key) {
 252        if (isset($form[$key]['#form_builder']['element_id'])) {
 253          // Save settings for this element.
 254        }
 255      }
 256    }
 257  }
 258  
 259  /**
 260   * @} End of "addtogroup hooks".
 261   */