[177a560] | 1 | <?php |
---|
| 2 | |
---|
| 3 | /** |
---|
| 4 | * @file |
---|
| 5 | * Provide dependent checkboxes that can be easily used in forms. |
---|
| 6 | * |
---|
| 7 | * This system will ensure that form items are invisible if the dependency is |
---|
| 8 | * not met. What this means is that you set the #dependency of an item to a |
---|
| 9 | * list of form ids that must be set, and the list of values that qualify. |
---|
| 10 | * |
---|
| 11 | * For a simple use, setting an item to be dependent upon a select box, if |
---|
| 12 | * any of the listed values are selected, the item will be visible. Otherwise, |
---|
| 13 | * the item will be invisible. |
---|
| 14 | * |
---|
| 15 | * If dependent upon multiple items, use #dependency_count = X to set the |
---|
| 16 | * number of items that must be set in order to make this item visible. This |
---|
| 17 | * defaults to 1. If set to 2, then at least 2 form items in the list must |
---|
| 18 | * have their items set for the item to become visible. |
---|
| 19 | * |
---|
| 20 | * When hiding checkboxes and radios you need to add their id in a div |
---|
| 21 | * manually via #prefix and #suffix since they don't have their own id. You |
---|
| 22 | * actually need to add TWO divs because it's the parent that gets hidden. |
---|
| 23 | * Also be sure to retain the 'expand_checkboxes' in the #process array, |
---|
| 24 | * because the views process will override it. |
---|
| 25 | * |
---|
| 26 | * Fieldsets can not be hidden by default. Adding '#input' => TRUE to the |
---|
| 27 | * fieldset works around that. |
---|
| 28 | * |
---|
| 29 | * For radios, because they are selected a little bit differently, instead of |
---|
| 30 | * using the CSS id, use: radio:NAME where NAME is the #name of the property. |
---|
| 31 | * This can be quickly found by looking at the HTML of the generated form, but |
---|
| 32 | * it is usually derived from the array which contains the item. For example, |
---|
| 33 | * $form['menu']['type'] would have a name of menu[type]. This name is the same |
---|
| 34 | * field that is used to determine where in $form_state['values'] you will find |
---|
| 35 | * the value of the form. |
---|
| 36 | * |
---|
| 37 | * The item that is dependent on, should be set to #tree = TRUE. |
---|
| 38 | * |
---|
| 39 | * Usage: |
---|
| 40 | * |
---|
| 41 | * First, ensure this tool is loaded: |
---|
| 42 | * @code { ctools_include('dependent'); } |
---|
| 43 | * |
---|
| 44 | * On any form item, add |
---|
| 45 | * - @code '#process' => array('ctools_dependent_process'), @endcode |
---|
| 46 | * - @code '#dependency' => array('id-of-form-without-the-#' => array(list, of, values, that, make, this, gadget, visible)), @endcode |
---|
| 47 | * |
---|
| 48 | * A fuller example, that hides the menu title when no menu is selected: |
---|
| 49 | * @code |
---|
| 50 | *function ctools_dependent_example() { |
---|
| 51 | * $form = array(); |
---|
| 52 | * $form['menu'] = array( |
---|
| 53 | * '#type' => 'fieldset', |
---|
| 54 | * '#title' => t('Menu settings'), |
---|
| 55 | * '#tree' => TRUE, |
---|
| 56 | * ); |
---|
| 57 | * $form['menu']['type'] = array( |
---|
| 58 | * '#title' => t('Menu type'), |
---|
| 59 | * '#type' => 'radios', |
---|
| 60 | * '#options' => array( |
---|
| 61 | * 'none' => t('No menu entry'), |
---|
| 62 | * 'normal' => t('Normal menu entry'), |
---|
| 63 | * 'tab' => t('Menu tab'), |
---|
| 64 | * 'default tab' => t('Default menu tab'), |
---|
| 65 | * ), |
---|
| 66 | * '#default_value' => 'none', |
---|
| 67 | * ); |
---|
| 68 | * |
---|
| 69 | * $form['menu']['title'] = array( |
---|
| 70 | * '#title' => t('Title'), |
---|
| 71 | * '#type' => 'textfield', |
---|
| 72 | * '#default_value' => '', |
---|
| 73 | * '#description' => t('If set to normal or tab, enter the text to use for the menu item.'), |
---|
| 74 | * '#process' => array('ctools_dependent_process'), |
---|
| 75 | * '#dependency' => array('radio:menu[type]' => array('normal', 'tab', 'default tab')), |
---|
| 76 | * ); |
---|
| 77 | * |
---|
| 78 | * return system_settings_form($form); |
---|
| 79 | *} |
---|
| 80 | * @endcode |
---|
| 81 | * |
---|
| 82 | * An example for hiding checkboxes using #prefix and #suffix: |
---|
| 83 | * @code |
---|
| 84 | *function ctools_dependent_example_checkbox() { |
---|
| 85 | * $form = array(); |
---|
| 86 | * $form['object'] = array( |
---|
| 87 | * '#type' => 'fieldset', |
---|
| 88 | * '#title' => t('Select object type'), |
---|
| 89 | * '#tree' => TRUE, |
---|
| 90 | * ); |
---|
| 91 | * $form['object']['type'] = array( |
---|
| 92 | * '#title' => t('Object type'), |
---|
| 93 | * '#type' => 'radios', |
---|
| 94 | * '#options' => array( |
---|
| 95 | * 'view' => t('View'), |
---|
| 96 | * 'node' => t('Node'), |
---|
| 97 | * 'field' => t('Field'), |
---|
| 98 | * 'term' => t('Term'), |
---|
| 99 | * ), |
---|
| 100 | * '#default_value' => 'view', |
---|
| 101 | * ); |
---|
| 102 | * |
---|
| 103 | * $form['object']['elements'] = array( |
---|
| 104 | * '#title' => t('Select the elements to load from the node.'), |
---|
| 105 | * '#type' => 'checkboxes', |
---|
| 106 | * '#prefix' => '<div id="edit-elements-wrapper"><div id="edit-elements">', |
---|
| 107 | * '#suffix' => '</div></div>', |
---|
| 108 | * '#process' => array('ctools_dependent_process', 'expand_checkboxes'), |
---|
| 109 | * '#dependency' => array('radio:menu[type]' => array('node')), |
---|
| 110 | * '#options' => array( |
---|
| 111 | * 'body' => t('Body'), |
---|
| 112 | * 'fields' => t('Fields'), |
---|
| 113 | * 'taxonomy' => t('Taxonomy'), |
---|
| 114 | * ), |
---|
| 115 | * '#default_value' => array('body', 'fields'), |
---|
| 116 | * ); |
---|
| 117 | * |
---|
| 118 | * return system_settings_form($form); |
---|
| 119 | *} |
---|
| 120 | * @endcode |
---|
| 121 | */ |
---|
| 122 | |
---|
| 123 | /** |
---|
| 124 | * Process callback to add dependency to form items. |
---|
| 125 | */ |
---|
| 126 | function ctools_dependent_process($element, $edit, &$form_state, &$form) { |
---|
| 127 | if (isset($element['#dependency'])) { |
---|
| 128 | if (!isset($element['#dependency_count'])) { |
---|
| 129 | $element['#dependency_count'] = 1; |
---|
| 130 | } |
---|
| 131 | if (!isset($element['#dependency_type'])) { |
---|
| 132 | $element['#dependency_type'] = 'hide'; |
---|
| 133 | } |
---|
| 134 | |
---|
| 135 | $js = array( |
---|
| 136 | 'values' => $element['#dependency'], |
---|
| 137 | 'num' => $element['#dependency_count'], |
---|
| 138 | 'type' => $element['#dependency_type'], |
---|
| 139 | ); |
---|
| 140 | |
---|
| 141 | if (!empty($form_state['ajax'])) { |
---|
| 142 | $form_state['js settings']['CTools']['dependent'][$element['#id']] = $js; |
---|
| 143 | } |
---|
| 144 | else { |
---|
| 145 | ctools_add_js('dependent'); |
---|
| 146 | $options['CTools']['dependent'][$element['#id']] = $js; |
---|
| 147 | drupal_add_js($options, 'setting'); |
---|
| 148 | } |
---|
| 149 | } |
---|
| 150 | |
---|
| 151 | return $element; |
---|
| 152 | } |
---|
| 153 | |
---|