[documentation] [Documentation task] Update API documentation for forms api #type => item

[RobRoy]

Issue status update for 
http://drupal.org/node/88274
Post a follow up: 
http://drupal.org/project/comments/add/88274

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  Jax
 Updated by:   RobRoy
-Status:       patch (code needs review)
+Status:       fixed

NM, I was logged in as anonymous. Fixed in DRUPAL-4-7.




RobRoy



Previous comments:
------------------------------------------------------------------------

Mon, 09 Oct 2006 18:07:38 +0000 : Jax

There is no mention of the 'item' type in the forms api documentation:
http://api.drupal.org/api/4.7/file/developer/topics/forms_api_reference....


It's missing from the HEAD docs too.




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:15:16 +0000 : RobRoy

I just noticed '#type' => 'item' is used in the forward.module. AFAIK
there is no 'item' FAPI type. Since it doesn't exist, the default type
'markup' is used.




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:27:35 +0000 : Jax

It's also used in the image_attach module and a lot of core modules:
$ grep "type' => 'item'" *.module
comment.module:      $form['_author'] = array('#type' => 'item',
'#title' => t('Your name'), '#value' => theme('username', $user)
contact.module:      $form['from'] = array('#type' => 'item',
contact.module:      $form['to'] = array('#type' => 'item',
menu.module:      $form['menu']['advanced'] = array('#type' => 'item',
menu.module:  $form['settings_links']['intro'] = array('#type' =>
'item',
menu.module:  $form['settings_authoring']['intro'] = array('#type' =>
'item',
menu.module:    $form['_path'] = array('#type' => 'item',
search.module:  $form['basic'] = array('#type' => 'item', '#title' =>
$prompt);
system.module:        $form['themes'][$info->key]['description'] =
array('#type' => 'item', '#title' => $info->name,  '#value' =>
dirname($info->filename) . ($info->name == variable_get('theme_default',
'bluemarine') ? t('<br /> <em>(site default theme)</em>') : ''));
system.module:  $form['settings'] = array('#type' => 'item', '#value'
=> $status);
system.module:    $form[$info->name]['description'] = array('#type' =>
'item', '#title' => $info->name,  '#value' => dirname($info->filename));


Since it is used in so many places I think the docs should at least
mention something about it...




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:30:10 +0000 : Jax

Even if it's just something like: "Since it doesn't exist, the default
type 'markup' is used."
I saw it in the code, wanted to know what it does, checked the docs,
found nothing. So just the sentence above would already be helpful.


And I would like to know which attributes it supports, because I'm
under the impression that it doesn't take #attributes.




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:36:01 +0000 : RobRoy

I think one of the higher ups should comment here. We should either
document it like Jax is saying OR submit patches to change those '#type'
=> 'item's to markups (we could remove the lines altogether but I think
it is better to be explicit for learning's sake). I'd prefer the latter
since it would avoid confusion in the future and there's no need to lead
people to believe that we have duplicate types.




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:44:40 +0000 : chx

<?php
function theme_item($element) {
 
return theme('form_element', $element, $element['#value'] . $element['#children']);
}
function theme_markup($element) {
  return $element['#value'] . $element['#children'];
}
?>
Item is a form element and rendered as many other form elements, with
an enclosing div, a possible title (w/ label) and possible description.
All these are missing from markup.




------------------------------------------------------------------------

Mon, 09 Oct 2006 18:47:46 +0000 : RobRoy

I stand corrected...and lazy since with a bit of looking I could have
actually researched that. My bad. Good call Jax and chx. :P




------------------------------------------------------------------------

Mon, 09 Oct 2006 19:32:15 +0000 : RobRoy

Attachment: http://drupal.org/files/issues/item.patch (8.88 KB)

I thought I had write access to DOCs repo. Can someone grant me those?
Here's the patch I was going to commit to DRUPAL-4-7.