function conditional_fields_attach_dependency in Conditional Fields 4.x

Same name and namespace in other branches

1. 8 conditional_fields.module \conditional_fields_attach_dependency()
2. 7.3 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

array $form: The form where the dependency is attached.

string $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.

string $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.

array $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 conditionalFieldsStates() for available states.
• condition: The condition for the dependency to be triggered. See conditionalFieldsConditions() for available conditions.
• values_set: One of the following constants:
  • ConditionalFieldsInterface::CONDITIONAL_FIELDS_DEPENDENCY_VALUES_WIDGET: Dependency is triggered if the dependee has a certain value defined in 'value'.
  • ConditionalFieldsInterface::CONDITIONAL_FIELDS_DEPENDENCY_VALUES_AND: Dependency is triggered if the dependee has all the values defined in 'values'.
  • ConditionalFieldsInterface::CONDITIONAL_FIELDS_DEPENDENCY_VALUES_OR: Dependency is triggered if the dependee has any of the values defined in 'values'.
  • ConditionalFieldsInterface::CONDITIONAL_FIELDS_DEPENDENCY_VALUES_XOR: Dependency is triggered if the dependee has only one of the values defined in 'values'.
  • ConditionalFieldsInterface::CONDITIONAL_FIELDS_DEPENDENCY_VALUES_NOT: Dependency is triggered if the dependee does not have any of the values defined in 'values'.
• value: The value to be tested when 'values_set' is ConditionalFieldsInterface::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 ConditionalFieldsInterface::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 conditionalFieldsEffects() for available effects and options.
• effect_options: The options for the active effect.
• selector: (optional) Custom jQuery selector for the dependee.

int $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 241

Contains conditional_fields.module.

Code

function conditional_fields_attach_dependency(&$form, &$form_state, $dependee, $dependent, $options, $id = 0) {

  // 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 = [
        '#field_name' => $dependee,
        '#parents' => [
          $dependee,
        ],
      ];
      $dependent = [
        '#field_name' => $dependent,
        '#field_parents' => [
          $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['#parents'][0]]['parents'] = $dependee['#array_parents'];
    $form['#conditional_fields'][$dependee['#parents'][0]]['dependents'][$id] = [
      'dependent' => $dependent['#field_name'],
      'options' => $options,
    ];
  }

  // Attach dependent.
  if (!empty($dependent['#parents'])) {
    $dependent_parents = $dependent['#parents'];

    // If the field type is Date, we need to remove the last "date" parent key,
    // since it is not part of the $form_state value when we validate it.
    if ($dependent['#type'] == 'date') {
      array_pop($dependent_parents);
    }
  }
  elseif (isset($dependent['#field_parents'])) {
    $dependent_parents = $dependent['#field_parents'];
  }
  if (isset($dependent_parents)) {
    $form['#conditional_fields'][$dependent['#parents'][0]]['field_parents'] = $dependent_parents;
    $form['#conditional_fields'][$dependent['#parents'][0]]['dependees'][$id] = [
      'dependee' => $dependee['#field_name'],
      'options' => $options,
    ];
  }
}