Document Hidden Form Elements

Picking this up next.

Here's the first take. After looking at Token value, it didn't seem to need a usage example because it sounds like you never need to use it?

No worries... I'm out on a motorcycle adventure this week myself... and I was expecting you to be unavailable.

Let me try and explain. If you set #value, the value of the hidden form element will show up for the browser js to use, but the values returned by $form_state will be immutable. You could make the argument that with HTML5 people should just use data- attributes in other form elements, but this is the way #value has been used with hidden elements in the past. It might be useful to to know that this is in fact (or was in d7) true for all elements. You can set "#value" on a textfield and it will become immutable as well, even though the browser will still show the field and it will look like the user can edit it.

I realize this is a tricky thing to explain and welcome any insights or suggestions. I suppose that we could just not document the #value behavior, but I have had enough accidental uses of #value when I meant to use #default_value with hidden elements that I thought it worth mentioning in the docs.

Will certainly address #2 when I can.

Ok. Here's the changes as requested.

FYI: No one would probably ever use #value on a visible element as #disabled would be a much better choice.

hmm... This brings me back to feeling the need to document the distinction. I started searching for other examples in core by searching for all occurrences of '#type' => 'hidden'. Most of the examples use #value for things like entity_id, but some use it for Javascript behaviors. The Vertical Tabs control uses a default_tab hidden element so that you could keep track of the currently selected tab across form rebuilds. The books module uses it to keep track of a tree hash to help you understand if you have changed the tree via javascript when you finally do the form submission. (It actually uses #value and #default_value in the same forms on different elements for the original and modified hashes)

If you choose the wrong implementation here the code will simply break, and it seems to me that choosing #value vs. #default value is important to this control in a way that it is not to other controls. I cannot think of another control where you would normally make a choice as to whether to use #value vs. #default value.

What are your thoughts?

Here's a rewording that might be clearer.

You were clear enough. I just missed it in my haste, sorry. Here ya go.