Missing hook_field_widget_form_alter()

Another possible (but as-yet missing) solution would be a hook_field_validate_alter(). This would be especially useful in my use case--I need to alter the list of terms a user may submit in term reference fields of any widget on any entity type, and I want to be able to enforce that in validation in a portable way.

Looks like it needs to be $instance['entity_type'].

Oops, misclick.

field_multiple_value_form() doesn't get the entity as an arg apparently?

Edit: the only place I found the entity data in field_multiple_value_form() was inside $form. Would it needed to be added as an argument?

For anyone else struggling with this, here's the sort of workaround I'm implementing atm. (This is half-baked and needs some checks for whether stuff is defined, etc., but you get the idea.) Looping through everything on every form is definitely less than ideal, but it's the best I've come up with at present given that we want to handle any entity types. I actually don't even know if it will work for non-nodes yet, but at least the possibility is there...

Edit: improving it a little.

function taxonomy_access_form_alter(&$form, &$form_state, $form_id) {
  if (is_array($form_state) && !empty($form_state['field'])) {
    foreach ($form_state['field'] as $fieldname => $el) {
      foreach ($el as $langcode => $field) {
        if ($field['field']['type'] == 'taxonomy_term_reference') {
          if ($field['instance']['widget']['type'] == 'taxonomy_autocomplete') {
            // Add our damn autocomplete handler.                                                                             
            $form[$fieldname][$langcode]['#autocomplete_path']
              = 'taxonomy_access/autocomplete/' . $fieldname;

            // Add our damn validator.                                                                                        
            $form[$fieldname][$langcode]['#element_validate']
              = array('taxonomy_access_autocomplete_validate');

            // Set our damn default value.                                                                                    
            $form[$fieldname][$langcode]['#default_value']
              = taxonomy_access_autocomplete_default_value($form_state['build_info']['args'][0]->{$fieldname}[$langcode]);
          }
        }
      }
    }
  }
}

Couple folks on IRC pointed out we don't need to pass $entity_type and $entity as separate arguments. So here's a reroll without those in $context.

Just confirmed that this patch applies to 8.x and 7.x, and allows me to alter the widget form very cleanly. E.g., with the following:

function taxonomy_access_field_widget_form_alter(&$element, &$form_state, $context) {
  if ($context['field']['type'] == 'taxonomy_term_reference') {
    $element['#access'] = FALSE;
  }
}

Brilliant!

To add this, we would also need to add the hook documentation in field.api.php. Looking into this now.

Attached patch includes hook documentation.

we don't need to pass $entity_type and $entity as separate arguments

Is this info available through other means or...?

+++ b/modules/field/field.api.php
@@ -786,6 +787,11 @@ function hook_field_widget_info_alter(&$info) {
+ * Other modules may alter the form element provided by this function using
+ * hook_field_widget_form_alter().
+ *
+ * @see hook_field_widget_form_alter()

The additional @see is not necessary here.

+++ b/modules/field/field.api.php
@@ -836,6 +842,30 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
+ * @param $element
+ *   The form element as rendered by hook_field_widget_form().

"The field widget form element as constructed by ..."

17 days to next Drupal core point release.

#13: The entity is available in $form_state['build_info'], and the entity type is both there and in $instance IIRC.

I'll fix the other documentation issues, thanks.

Same as #12 but with hook documentation corrections.

Looks good to me at first glance, we usually put @see at the bottom of doxygen rather than the top.

It feels like $form/$form_state are going to be pretty different depending on where the widget is, is that a feature or not?

It feels like $form/$form_state are going to be pretty different depending on where the widget is, is that a feature or not?

This does seem like a possibility, but the hook is not introducing new behavior that is not already present in hook_field_widget_form(), which gets all of the above and then some as arguments:
hook_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element)

Perhaps we should consider changing the signature to match this, though.

If it's not new behaviour that seems fine.

Matching signatures wouldn't do any harm.

The signature cannot be matched further and should not I think -- the only difference is in $form vs. $element, but hook_field_widget_form() actually produces $element, not extending $form, so we're passing on $element to the _alter().

Checked with sun about this. For future reference: To use drupal_alter(), we need the first argument to be the thing we're altering--the field widget form element, in this case--and then up to two additional parameters, the last of which is an associative array containing as many other parameters as we want to feed the alter hook. $form_state is the next most reasonable thing to alter by reference, so it makes sense to have that as the second argument.

So, the signature is correct as it is.

@yched or another Field API/module maintainer needs to sign off this patch.

Will it backport to D7 ??

Should be IMO, tagging.

+++ b/modules/field/field.api.php
@@ -836,6 +840,30 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
+ *   - field: The field structure.
+ *   - instance: The field instance.

should be "the field instance structure"

+++ b/modules/field/field.api.php
@@ -836,6 +840,30 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
+  if ($context['field']['type'] == 'mytype') {
+    $element['#access'] = FALSE;
+  }

Nitpick : we might want to give an example discriminating on a specific widget type (i.e checking $context['instance']['widget']['type']). Sounds more "real life".

+++ b/modules/field/field.form.inc
@@ -76,6 +76,9 @@ function field_default_form($entity_type, $entity, $field, $instance, $langcode,
+          // Allow modules to alter the field widget form element.
+          $context['form'] = $form;

This is reusing the $context var built for the hook_field_widget_properties_alter() call a couple lines above. I'm not too fond of this, let's please build a fresh, dedicated $context var.

+++ b/modules/field/field.form.inc
@@ -76,6 +76,9 @@ function field_default_form($entity_type, $entity, $field, $instance, $langcode,
+          drupal_alter(array($function, 'field_widget_form'), $element, $form_state, $context);

This allows two variants :
a "targeted" hook_WIDGETMODULE_field_widget_form_alter(), and a "generic" hook_field_widget_form_alter().
- I think the core practice is to put the "targeted" variant second.
- The "targeted" variant needs to be documented as well.
- I don't think targeting by WIDGETMODULE is the right approach here. The same module can provide several widgets that are structured very differently. I'd say we'd rather want to target by widget type. As a developer, I know which widget I want to alter, I don't care which module provides it. Also, that fits with the "widgets as plugins" direction we'll want to push for if/when the WSCC initiative comes up with a plugins system.

Also, the alter hook doesn't receive the other params that the original hook_field_widget_form() 'callback' receives ($langcode, $items, $delta) ? I'd think those should b added to the context ?

More generally on the feature : I'm not opposed to this, but the symmetry between widgets and formatters raises the question of a similar hook_field_formatter_view_alter() hook on the formatter side - which we cautiously avoided so far for performance reasons (a listing page can call 100s of formatters, and field rendering is already quite slow).

14 days to next Drupal core point release.

Attached patch:

1. Moves the hook documentation's @see to the bottom of the docblock as suggest by catch in #16.
2. Creates separate context variables $properties_context and $form_context for the respective alter hooks.
3. Adds langcode, items, and delta to the context (as well as adding the entity type explicitly for consistency, since this is the pattern when the widget is built in field_multiple_value_form().
4. Uses overriding a widget autocomplete path for an example.

There are two points I haven't addressed:

+++ b/modules/field/field.api.php
@@ -836,6 +840,30 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
+ *   - field: The field structure.
+ *   - instance: The field instance.

should be "the field instance structure"

To clarify (since you quoted two lines). Should it read:

 *   - field: The field structure.
 *   - instance: The field instance structure.

+++ b/modules/field/field.form.inc
@@ -76,6 +76,9 @@ function field_default_form($entity_type, $entity, $field, $instance, $langcode,
+          drupal_alter(array($function, 'field_widget_form'), $element, $form_state, $context);

This allows two variants :
a "targeted" hook_WIDGETMODULE_field_widget_form_alter(), and a "generic" hook_field_widget_form_alter().
- I think the core practice is to put the "targeted" variant second.
- The "targeted" variant needs to be documented as well.
- I don't think targeting by WIDGETMODULE is the right approach here. The same module can provide several widgets that are structured very differently. I'd say we'd rather want to target by widget type. As a developer, I know which widget I want to alter, I don't care which module provides it. Also, that fits with the "widgets as plugins" direction we'll want to push for if/when the WSCC initiative comes up with a plugins system.

I am not sure how to address this.

Thx @xjm.

- $properties_context and $form_context :
I think both can be called $context. Those are one-off variables anyway, created just for the sake of the alter call.

- "field: The field structure. / instance: The field instance structure."
Yup :-)

- variants :
I'd suggest

drupal_alter(array('field_widget_form', 'field_widget_' . $instance['widget']['type'] . '_form'), ...)

Ah, it makes sense now. I agree this is a much better hook. In that case I will move the widget-specific example to that hook doc, and act based on field type in the generic one.

Attached incorporates suggestions from #24-26.

Oops, some trailing whitespace.

#28 but without the trailing whitespace.

Same patch applies to D7 fine. I confirmed that both the generic and specific hooks work as advertised.

Updated issue summary.

Added direct reference to most recent patch.

Thanks @xjm.

Polished a little further :
- Changed hook_field_widget_NAME_form_alter() to hook_field_widget_WIDGET_TYPE_form_alter()
- Adjusted the $context elements to match the args received by hook_field_widget_form(). The $form_state stays it's own parameter, as it's alterable.
- Adjusted the @see references in the phpDocs.

It's now up to someone else to RTBC, though :-/

Typo and clarity.

Thanks!

Noticed a typo (follwoing). I'll reroll quicklike. Yay green!

update status

Clearer indication that this is a small API addition, not a change.

Clearer.

Updated tasks.

Crossposting some issues that reference this one:
#982764: Document how to upgrade CCK field modules that used hook_widget_settings_alter
#672526: hook_widget_settings_alter() is missing in D7 (and D8) and several D6 modules cannot be ported to D7 because of this.
#1212142: How to alter widget type programmatically on a per-form basis?
as well as several in TAC.

In case it matters, I'm using this patch and the hooks work well.

I'm wondering - do you know when these changes will be added to a D7 release, or in which release they'll be included?

Thanks.

@j0rd: This patch has many eyes on it - i visit this page daily. Missing hook_field_widget_form_alter() is a D7 release blocker for several modules, so this patch is important for a lot of people.
@xjm: Thanks for the patch. It works as expected.

@j0rd: We are very eager to see this in core as well. +1 from my side

This is somewhat blocking a stable release of TAC at present.

It seems that this patch does have some eyes on it, and has been tested a few times. It is also necessary for a module I would like to release.

I'm not familiar with the process of getting patches committed to core. Is there anything we can do to speed it along? I personally don't many people in my twitter/google+ who I can share this with.

Marked #1212142: How to alter widget type programmatically on a per-form basis? as duplicate of this issue.

Moving to major since it's blocking stable contrib releases.

This looks like a pretty straight-forward oversight in the API. I'd been holding off on this patch while we got our bug counts down, but that seems to have been accomplished in the last couple of weeks, so cool.

Committed and pushed to 8.x and 7.x. Thanks a lot.

Corrected name of specific hook in summary.