From sun in #375907-32: Make text field use D7 '#text_format' selector :
- #value_callback is a yet-undocumented FAPI feature (I guess this is about http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/7 ?)
- The signature of core's existing implementations is :

function form_type_checkbox_value($form, $edit = FALSE) {

while the $form should actually be $element.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

sun’s picture

Issue tags: +Novice

subscribing and tagging

JamesAn’s picture

With respect to the signature of form_type_checkbox_value(), should we also consider renaming $form to $element for all these similar functions:
form_type_checkboxes_value(),
form_type_image_button_value(),
form_type_password_confirm_value(),
form_type_select_value(),
form_type_textfield_value(), and
form_type_token_value?

Reading the code that processes the FAPI feature, #value_callback, I just want to clarify my understanding of it. #value_callback is:
* not used if #value is set (they should not both be set simultaneously for any form element.),
* called and #value is set to its return value, and
* used by all special elements that use #value (button, hidden, image_button, submit, and value).

Both these fixes need to be done for D6 and 7, right?

Unfortunately, there are no examples in core to showcase the use of #value_callback.

sun’s picture

Issue tags: +API clean-up

Tagging for feature freeze.

Anonymous’s picture

Oh hey there undocumented Form API property #value_callback which I need very much to use. Looks like I will be documenting this before I can justify getting around to using it.

cfennell’s picture

Status: Active » Needs review
FileSize
1.45 KB

A stab at documenting the callback and a fix for another small documentation error ("@param $form" becomes "@param $element").

Dries’s picture

Status: Needs review » Needs work

The documentation should explain _why_ and _when_ this should be used. It lacks context right now. Thanks! :)

ldweeks’s picture

Status: Needs work » Needs review

I found '#value_callback' in looking through the D6 version of CCK, and I assume that it appears here because fields are now in core. I am trying to figure out the answers to "why" and "when" (as Dries put it), and came across this information:

There is another way to set the value for the field, by adding '#value_callback' to hook_element() or to your form element, and providing a custom function to use to set the value. That callback will get the same arguments as above, but provides a more flexible way to set a value. You can use that to set a value on a nested sub-element like those CCK uses, to use the same value callback for several different elements, or to add a custom value callback to standard FAPI element type.

That snippet is from the d6 example form section of the drupal handbook: Creating Custom Elements Using Drupal 6.x , under "Value callback or form_type_hook_value()".

I don't know if that information is correct - someone more knowledgable needs to vouch for it - but if it is, perhaps we can re-use some of that documentation in the D7 docs.

Dave Kopecek’s picture

>> Unfortunately, there are no examples in core to showcase the use of #value_callback.

For future searchers: #value_callback is used in D6 nodereference.module

read nodereference.module code alongside: http://drupal.org/node/169815 ( Creating Custom Elements Using Drupal 6.x ) per #8.

chx’s picture

Assigned: Unassigned » chx
Issue tags: -Novice

Dries' question cries for a FAPI expert not a novice...

howto’s picture

Issue tags: -API clean-up

Status: Needs review » Needs work

The last submitted patch, value_callback_documentation-447930.patch, failed testing.

franz’s picture

Status: Needs work » Needs review
Issue tags: +API clean-up
franz’s picture

Version: 7.x-dev » 8.x-dev
Issue tags: +Needs backport to D7

Status: Needs review » Needs work

The last submitted patch, value_callback_documentation-447930.patch, failed testing.

franz’s picture

Status: Needs work » Needs review
FileSize
1.28 KB

re-rolled

Mile23’s picture

API docs still missing from http://api.drupal.org/api/drupal/modules--system--system.api.php/functio... and the D7 version as well.

Assuming the content is correct, here it is.

chx’s picture

Status: Needs review » Needs work

Thanks for working on the patch! However, by now the doxygen of form_builder seems to mention #value_callback. That documentation however needs a signature. So this patch says "+ * Such callbacks are passed three values: $element, $input, and $form_state" which is correct but it needs to explain that $input will be FALSE when the default value needs such mapping. Also needs to mention that you need to return the value. Also if you look there then the #process and the #after_build functions also lack signatures and return values. #process gets $element, $form_state, $complete_form these arguments and needs to return the $element. #after_build gets $element, $form_state and also needs to return the $element (here the complete form can be found in $form_state['complete_form']).

Thanks again.

joachim’s picture

Component: forms system » documentation
Assigned: chx » Unassigned

This should probably be in the docs component, and unassigned now chx has reviewed it.

jhodgdon’s picture

There are also some formatting problems at the top of this patch:

/**
  * Populate the #value and #name properties of input elements so they
  * can be processed and rendered.
+ *
+ * Each input element may pass an optional #value_callback argument to specify 
+ * a function through which input data is filtered before being passed to the
+ * #value property. If no #value_callback argument is present, a default
+ * callback is attempted based upon the input element's #type property:
+ *   'form_type_' . $element['#type'] . '_value';
+ * Such callbacks are passed three values: $element, $input, and $form_state:
+ *   $element['#value'] = $value_callback($element, $input, $form_state);
  */
 function _form_builder_handle_input_element($form_id, &$element, &$form_state) {

- First line: see http://drupal.org/node/1354#functions
- Don't indent stuff in paragraphs randomly. Use @code for code, or a bullet list, or just wrap it within the paragraph (which is what will happen on api.drupal.org for random indents anyway).
- Code fragments probably should not end in ; (such as that first one, which is not an assignment).
- The second-to-last line repeats information that is in the last line unnecessarily.

In the last hunk of the patch:

+ *    #type property: 'form_type_' . $element['#type'] . '_value';

This should not end in ; and maybe something should be added there about what the function takes as arguments?

johnv’s picture

Title: #value_callback documentation and signature » #value_callback documentation and signature (D7)
Issue summary: View changes
Status: Needs work » Closed (won't fix)

ITMT this is already fixed in D8 in FormBuilderInterface.php:

public function prepareForm($form_id, &$form, FormStateInterface &$form_state);
  // ...
   * - $element['#value_callback']: A callable that implements how user input is
   *   mapped to an element's #value property. This defaults to a function named
   *   'form_type_TYPE_value' where TYPE is $element['#type'].
  // ...

I I guess this won't make it into D7. It's already on the Form API documentation, and all efforts are in D8.
Also, there's better info on the net, see:
https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.h...
http://drupal.stackexchange.com/questions/125386/how-does-value-callback...

(I wish I found this property earlier - years ago. )

jhodgdon’s picture

Status: Closed (won't fix) » Active
Issue tags: -API clean-up, -Needs backport to D7

Actually, since this is a documentation issue, there is no reason we cannot fix it in Drupal 7. We just need a viable patch.

johnv’s picture

Version: 8.0.x-dev » 7.x-dev

Let's set the version accordingly. Is missing documentation a bug?

jhodgdon’s picture

Yes, missing or incorrect documentation is a bug. Thanks!