You are here

Home » API reference » Conditional Fields 7.3 » conditional_fields.module

function conditional_fields_attach_dependency in Conditional Fields 7.3

Same name and namespace in other branches
  1. 8 conditional_fields.module \conditional_fields_attach_dependency()
  2. 4.x conditional_fields.module \conditional_fields_attach_dependency()

Attaches a single dependency to a form.

Call this function when defining or altering a form to create dependencies dynamically.

Parameters

$form: The form where the dependency is attached.

$dependee: The dependee field form element. Either a string identifying the element key in the form, or a fully built field array. Actually used properties of the array are #field_name and #parents.

$dependent: The dependent field form element. Either a string identifying the element key in the form, or a fully built field array. Actually used properties of the array are #field_name and #field_parents.

$options: An array of dependency options with the following key/value pairs:

  • state: The state applied to the dependent when the dependency is triggered. See conditional_fields_states() for available states.
  • condition: The condition for the dependency to be triggered. See conditional_fields_conditions() for available conditions.
  • values_set: One of the following constants:
  • value: The value to be tested when 'values_set' is CONDITIONAL_FIELDS_DEPENDENCY_VALUES_WIDGET. An associative array with the same structure of the dependee field values as found in $form_states['values] when the form is submitted. You can use field_default_extract_form_values() to extract this array.
  • values: The array of values to be tested when 'values_set' is not CONDITIONAL_FIELDS_DEPENDENCY_VALUES_WIDGET.
  • value_form: An associative array with the same structure of the dependee field values as found in $form_state['input']['value']['field'] when the form is submitted.
  • effect: The jQuery effect associated to the state change. See conditional_fields_effects() for available effects and options.
  • effect_options: The options for the active effect.
  • element_view: An associative array of field view behaviors with CONDITIONAL_FIELDS_FIELD_VIEW_* constants as keys and the same constants as values for enabled behaviors and 0 for disabled behaviors. See conditional_fields_behaviors() for descriptions.
  • element_view_per_role: Set to 1 to activate field view settings per role.
  • element_view_roles: An associative array of field view settings per role where the keys are role ids and the values are arrays with the same structure of 'element_view'.
  • element_edit: An associative array of field edit behaviors with CONDITIONAL_FIELDS_FIELD_EDIT_* constants as keys and the same constants as values for enabled behaviors and 0 for disabled behaviors. See conditional_fields_behaviors() for descriptions.
  • element_edit_per_role: Set to 1 to activate field edit settings per role.
  • element_edit_roles: An associative array of field edit settings per role where the keys are role ids and the values are arrays with the same structure of 'element_edit'.
  • selector: (optional) Custom jQuery selector for the dependee.

$id: (internal use) The identifier for the dependency. Omit this parameter when attaching a custom dependency.

Note that you don't need to manually set all these options, since default settings are always provided.

1 call to conditional_fields_attach_dependency()
conditional_fields_element_after_build in ./conditional_fields.module
Processes form elements with dependencies.

File

./conditional_fields.module, line 358
Define dependencies between fields based on their states and values.

Code

function conditional_fields_attach_dependency(&$form, $dependee, $dependent, $options, $id = 0) {
  $options += conditional_fields_dependency_default_options();

  // The absence of the $id parameter identifies a custom dependency.
  if (!$id) {

    // String values are accepted to simplify usage of this function with custom
    // forms.
    if (is_string($dependee) && is_string($dependent)) {
      $dependee = array(
        '#field_name' => $dependee,
        '#parents' => array(
          $dependee,
        ),
      );
      $dependent = array(
        '#field_name' => $dependent,
        '#field_parents' => array(
          $dependent,
        ),
      );

      // Custom dependencies have automatically assigned a progressive id.
      static $current_id;
      if (!$current_id) {
        $current_id = 1;
      }
      $id = $current_id;
      $current_id++;
    }
  }

  // Attach dependee.
  // Use the #array_parents property of the dependee instead of #field_parents
  // since we will need access to the full structure of the widget.
  if (isset($dependee['#parents'])) {
    $form['#conditional_fields'][$dependee['#field_name']]['parents'] = $dependee['#array_parents'];
    $form['#conditional_fields'][$dependee['#field_name']]['dependents'][$id] = array(
      'dependent' => $dependent['#field_name'],
      'options' => $options,
    );
  }

  // Attach dependent.
  if (isset($dependent['#field_parents'])) {
    $dependent_parents = $dependent['#field_parents'];
  }
  elseif (isset($dependent['#parents'])) {
    $dependent_parents = $dependent['#parents'];
  }
  if (isset($dependent_parents)) {
    $form['#conditional_fields'][$dependent['#field_name']]['field_parents'] = $dependent_parents;
    $form['#conditional_fields'][$dependent['#field_name']]['dependees'][$id] = array(
      'dependee' => $dependee['#field_name'],
      'options' => $options,
    );
  }

  // Actual processing is done in conditional_fields_form_after_build().
  // Append the property so the callback runs last.
  _conditional_fields_element_add_property($form, '#after_build', 'conditional_fields_form_after_build', 'append');
}