The API doc for hook_element_info() is extremely outdated---it only talks about form elements (even though the "elements" provided through this hook are now types for renderable arrays, cf. system_element_info() and http://drupal.org/node/930760 .
It also does not document the vital #theme and #theme_wrapper properties that are used in such more general elements.
I'd be willing to roll a patch in the next couple of days to get the doc for this function updated, unless someone more experienced than me wants to step in.
| Comment | File | Size | Author |
|---|---|---|---|
| #5 | 1230700-doc-hook_element_info-5.patch | 5.87 KB | sven.lauer |
| #2 | 1230700-doc-hook_element_info.patch | 5.97 KB | sven.lauer |
Comments
Comment #1
jhodgdonPlease do roll a patch, thanks!
Comment #2
sven.lauer commentedHere is a first stab at a patch. It is quite lengthy, but this is in part because it is rather unintuitive that #types can be DECLARED just by specifying their default values (it is a very ELEGANT way to do it, but not quite intuitive). And it seems this hook, or alternatively an associated handbook page is the place to do it. Hence the lengthy explanation of the examples. I could be convinced that some of this information is too detailed for a doc block.
I also included a short paragraph about this being the not-quite-equivalent of hook_elements() in D6, which is something that is not done often in the API doc, so maybe this is against common practice. Please advise ;)
Also, I did not break the lines within @link ... @endlink directives intentionally, as I was not sure whether the parser can handle line breaks in there. I'd be happy to re-roll with line breaks.
Feedback much appreciated.
Comment #3
sven.lauer commentedAnother thing: I think the sample hook implementation here could use a more useful example---maybe a subset of system_element_info()? Is the doc queue the right place to talk about something like that?
Comment #4
jhodgdonThe sample hook implementation for this function should be discussed right here.
I don't have time at this moment to look at this patch in detail, but one thing I noticed right away is the first line, which doesn't conform to standards (should be one line, not wrapped, and start with a different verb -- please look at hook standards on http://drupal.org/node/1354 or I can elaborate later -- probably not for a few weeks though as I'm leaving tomorrow for DrupalCon London).
Also needs some proofing... anyway I will get back to this eventually, but you might make a second pass and make sure the whole thing makes sense and conforms to standards...
Comment #5
sven.lauer commentedRight, the initial line thing escaped my attention because I only edited it (I also blame the retention of the awkward / non-standard "allow" on that ;).
The attached patch fixes both things, and some of the omitted/doubled articles and punctuation. Also add a reference to theme() when mentioning overriding of theme functions.
Have fun at DrupalCon!
Comment #6
jhodgdonFirst line is better... I've found some time to review the patch:
This needs some wrapping attention... and "which" should always have a comma before it (or else it should be "that").
But this paragraph doesn't seem right to me. "allows modules to declare element types" -- yes. "this is done by specifying default values"??? That's not all you have to do to declare an element type, so that sentence doesn't make sense to me.
Should that first line be: "via an implementation of this hook"? And maybe in place of "can use the name" something like "can declare an element of this type by using the name"?
I like the example... but maybe if you're going to talk about the #tag property in the usage example, you should put that into the simplified declaration? Or otherwise explain how you would know that #tag is a property (like looking at the theme function, if that is where it is)? Oh I see, you explain that below... but I had sort of a "what?!? where did that come from" moment when I saw that, so maybe the explanation should be moved up?
Case of what? Is this related to the previous discussion, or are you starting a new discussion?
We don't document D6 to D7 changes in D7/8 documentation. You can put a comment on the d6/7 corresponding function pages on api.drupal.org to link them together, and changes are documented on the API change pages/change nodes.
One more thing: I'm not sure if I agree with taking out the list of commonly-used array elements for types. You don't think this was useful?
Comment #7
jhodgdonBack to the original report, it was asking #theme_wrapper and #theme to be *added*, not for the list of standard elements to be removed...
Comment #8
sven.lauer commentedI'll re-roll another version of this patch, some comments (possible reactions to these might help me improve these parts):
I know that sound weird/counter-intuitive, but that is exactly how it works, technically (unless I am completely misunderstanding things. But I think I would have noticed that implementing #types and reading the code): All you have to do to declare a #type is to implement this hook and specify default values for its #-properties. Once you have done this, you can use the #type.
Of course, in most cases, these default values will refer to callback functions that you'll want to implement for things to work correctly. But this is not necessarily the case. For example, I could "declare" a type by having the following in my hook_element_info()-implementation:
And given that theme_html_tag() is implemented in core, I am done. I could use something like
which would be rendered as:
The example is artificial, but the point, more generally, is that you could be done with all your implementation work simply by making use of callback functions defined by other people.
Perhaps, we should avoid of #types being "declared" at all, for in a very real sense, there are not declared anywhere at all. Then again, what makes the render/form API aware of a #type is precisely the definition of this hook, so it does make some sense to speak of them being "declared" here.
Point taken. When I read the text for the first re-roll, I actually thought something similar---that I should mention the #tag in the text before.
Part of the reason for choosing THIS example (besides 'html_tag' being very simple) is that '#tag' is NOT part of the "declaration" of the type. Because the properties of a type are not declared in the implementation of this hook, only default values are provided. They are really not declared anywhere (but specified in the documentation of the theme functions, in most cases). I'll try to think of a way to make this more clear.
Comment #9
jhodgdonWell, I still think the statement about "all you need to do" is a bit misleading, since the normal case is that you would need to write some theme or process types of functions. Maybe it could be clarified a bit?
Comment #10
sven.lauer commentedWhen I re-roll the patch, I will try and be somewhat clearer on this, by adding to/rewriting the initial paragraph to mention the implementation of callback functions.
Comment #11
jhodgdonThis needs to incorporate:
#348581: API documentation of hook_elements
#2234571: hook_element_info does not mention #value_callback
(which I'm marking as duplicates in a moment).
Comment #12
jhodgdonWe have another duplicate issue that also has a patch:
#2015177: Update documentation around hook_element_info() to not say/imply element types are limited to the Form API
Comment #26
quietone commentedhook_element_info was removed in #2311393: Remove hook_element_info() and all references to it.