Explain #tree in element example (and rework Element Example!)

Sorry - I heartily agree with you. The Element example hasn't really been worked on yet since it migrated to Examples. It's pretty old and moldy.

Your contribution is welcome.

#tree is a standard part of the form API, and I (think) that when it's used in the newer Form example it's explained. It's also described in the Form API reference.

Regarding #tree, lets use this as an example

$form['bike'] = array(
 '#type' => 'fieldset',
 ...
);
$form['bike']['wheels'] = array( ... );

As show in the submit function, to get the value of wheels you would use $form_state['values']['wheels']
If we set #tree like this

$form['bike'] = array(
 '#type' => 'fieldset',
 '#tree' => TRUE,
 ...
);
$form['bike']['wheels'] = array( ... );

then to get the value of wheels you would use $form_state['values']['bike']['wheels']

Hello rfay. I'm Khalid, the newcomer you met yesterday at the Coder Lounge.

As you suggested me, I tried to bring more examples to the element_example.module. Next step will be either to write a test to make sure it works or merge it into the form_example.module. The patch mainly consists of more comments and explanations.

I also noticed that there is no "Element Example" Component in the issue queue, so merging it to form_example makes even more sense.

As this is my first patch ever, feedback is very welcome !

Congratulations, Khalid, and welcome!

I don't know why the test submission didn't happen. But your patch should be made from the root of the examples project, so your diff have form_example/xxx in it.

Welcome!

The same, made from the root. Thank you teacher !

I had to put in the "need review" status so the test happens.

I re-rolled it with the last dev, and some more explanations than my previous patch, and added a regular expression test for the third part of the element. Hope this one will do it !

Sorry, forgot to roll it from the root of the module.

I apologize that I won't be able to review for the next week, but I very much appreciate your work on this.

No problem, until then I will surely write other patches for the module :)

This is a complete rewrite, moving element_example into form_example, doing cleanups, and adding 3 new element types, from simple to complex. It also adds tests.

@matslats, you may find your question from #3 answered here, as there is a phonenumber field that keeps the value all as one item, and there is one that keeps it in the array. There are also trivial textfield and checkbox examples.

Left in stuff that should have been merged away. Retry.

Without the removal of element_example

Committed to DRUPAL-6--1: http://drupal.org/cvs?commit=416576

Now on to D7

Here is the D7 version, thanks to DamZ's help!

Subscribing to review today.

Thanks Dave, how is the review going?

So, D7 HEAD just installed, examples HEAD just installed, applied the patch at #19, enable the form example module, and when I go to 'examples/form_example/element_example' I get this error:

Fatal error: Cannot create references to/from string offsets nor overloaded objects in C:\webdev\www\dev7\includes\common.inc on line 5755

The form element example is not working untill the berdir's patch at #913528: Create new boolean field "Cannot create references to/from string offsets nor overloaded objects" (#14) gets commited.

The only concern I do have with this patch is about the element processing functions..
- form_example_phonenumber_discrete_process uses '#value' to store the default value
- form_example_phonenumber_combined_process uses '#default_value# to store the default value. This may lead to confusion.

In fact, it is not clear the usage of these functions. They are defining the form field element, buy they don't have enough documentation to clearly state (as an example) that they should get element's default value and process it into the sub-elements of the field.

Appart from that, patch looks pretty!! good work!

Bumping to the top of the list because of the '#value' and '#default_value' question (the reason why I marked as needs work).

should form_example_phonenumber_discrete_process use '#default_value' instead? I'd say yes.. with that change I'd put rtbc but not commit.

Appart from that, patch applies, the reason it does not work is because of the core bug.

#tree gets explained, at least from my pov.

BTW: the #group is not explained in the form example.. is it important enough to include a sample?

I haven't debugged or looked at the problem with this. Is there some other way we should do the offending item? Otherwise, we can just wait for the core patch to go in.

I'd suggest to fix the #value -> #defaut_value first, and keep as rtbc, but don't commit until core gets fixed.

Love me, baby...

Looks like the evil commit was #763376: Not validated form values appear in $form_state, that make also field api and file modules to fail. As it seems that issue #913528: Create new boolean field "Cannot create references to/from string offsets nor overloaded objects" is not going to solve our problem, I've done a little hack in the combined field.

It is 99% Randy's patch at #19 with a few cleanups from coder and a new '#value_callback' for the combined field. This value callback works only when form builder is not proccessing the element, so it puts the values in the propper way.

Someone with more knowledge than me in form API, please, review that callback hack to see if it is done the right way, becuase the rest of the patch is untouched.

I'll try to give this a look. I'm going to be in one of those crazy training things all week though, so it may sit for awhile.

A few comments from looking at the patch without trying it out:

1) The question of #value vs #default_value. A value_callback should be using #default_value. A process should be using #value (#value has been set by the time you get to #process and altering #default_value won't/shouldn't have any effect). The exception to this is if the process is creating a new sub-value that hasn't yet been processed (i.e. a form element is creating a new sub-element of type #textfield). Since the sub-element hasn't yet been processed, it needs to have #default_value rather than #value set.

2) The example has two value callbacks that use different patterns:

function form_example_phonenumber_combined_value(&$element, $input = FALSE, $form_state = NULL) {
}

function form_type_form_example_checkbox_value($form, $edit = FALSE) {
}

The first is a custom callback declared in hook_elements(). The second is the type of value callback that FAPI detects automatically (form_type_ELEMENTTYPE_value). Using both in the same example without providing any explanation is confusing. Plus they both should have the same arguments.

The code comments need a bit of work "Implements hook_xxx" rather than "Implementation of xxx". Also, there are a number of references to hook_elements() in the comments rather then hook_element_info().

Eg:

Implementation of form_example_elements(). should be Implements hook_element_info().

Wow, lost track of this one. Was wondering where this went!

#26: element_example_26.patch queued for re-testing.

This is a reroll of #26 to current HEAD.

It still needs #27, #29, and #30 done to it.

I'd really like to get this one in. I'm just stuck on doing #29 correctly. I guess this is element stuff, not field stuff, so it shouldn't be that hard to get done. But I would really like to get this one in before it goes completely stale. Maybe I'll be able to do it on the plane Friday.

AFAICT, these patch and other patch about form rendering stuff were linked somehow, but can't remember wich one depends on the other.. Perhaps we can 'restart' the form issues..

sorry, I meant the 'other' form issues

I am working away on this one and it's improved quite a lot. I hope to have a patch in the next week or so.

Here is the current version. I believe it deals with #29 and #30.

I'm totally sick of this one so hope it's RTBC or somebody can take a little bit of it on themselves.

Whoops.

Committed. Finally. 981bdedded413e4be735e55c82f034914e7f8391