[Summary view] [Print] [Text view]

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