Form Reference
-
Upload
mailtopramodbwd -
Category
Documents
-
view
222 -
download
0
Transcript of Form Reference
-
8/8/2019 Form Reference
1/17
Home
forms_api_reference.html
View documentation View source
Version 1.81.2.6 (checked in on 2009/03/07 at 16:39:07 by darthsteven)
This document provides a programmer's reference to the Drupal Forms API. If you're interested in step-by-step documentation to help you writeforms, please see the Forms API QuickStart guide .
Skip to: Properties | Default Values | Elements
Form Controls
Legend:X = attribute can be used with this type- = this attribute is not applicable to this type
Special Elements
#type checkbox checkboxes date fieldset file password rad io radios se lec t t ex ta rea tex t f ie ld
#access X X X X X X X X X X X
#ahah X - - - - X X - X X X
#after_build X X X X X X X X X X X
#attributes X X X X X X X X X X X
#autocomplete_path - - - - - - - - - - X
#collapsed - - - X - - - - - - -
#collapsible - - - X - - - - - - -
#cols - - - - - - - - - X -
#default_value X X X - - - X X X X X
#delta - - - - - - - - - - -
#description X X X X X X X X X X X
#disabled X X X - X X X X X X X
#element_validate X X X X X X X X X X X
#field_prefix - - - - - - - - - - X
#field_suffix - - - - - - - - - - X
#maxlength - - - - - - - - - - X
#multiple - - - - - - - - X - -
#options - X - - - - - X X - -
#parents X X X X X X X X X X X #prefix X X X X X X X X X X X
#required X X X - - X X X X X X
#return_value X X - - - - X X - - -
#rows - - - - - - - - - X -
#size - - - - - - - - X - X
#suffix X X X X X X X X X X X
#theme X X X X X X X X X X X
#title X X X X X X X X X X X
#tree X X X X X X X X X X X
#weight X X X X X X X X X X X
# type button image_button submit form hidden markup item value
#after_build X X X X X X X -
#ahah X X X - - - - -
#action - - - X - - - -
#attributes X X X X X X - -
#button_type X X X - - - - -
#default_value - - - - X - - -
#description - - - - - - X -
#element_validate X X X - X X X X
#executes_submit_callback X X X - - - - -
#method - - - X - - - -
#parents X X X - X - - X
#prefix X X X X X X X -
#redirect - - - X - - - -
#required - - - - X - - -
Drupal 4.7 Drupal 5 Drupal 6 Drupal 7
Search Drupal 6
io n, file, or topic: * Search
upal 6 nstants es nctions obals pics
DDeveloping for DrupalReport a bug
http://api.drupal.org/supporthttp://drupal.org/http://api.drupal.org/supporthttp://api.drupal.org/supporthttp://drupal.org/contributors-guidehttp://drupal.org/contributors-guidehttp://drupal.org/http://api.drupal.org/api/groupshttp://api.drupal.org/api/globalshttp://api.drupal.org/api/functionshttp://api.drupal.org/api/fileshttp://api.drupal.org/api/constantshttp://api.drupal.org/apihttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#requiredhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#redirecthttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#prefixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#parentshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#methodhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#executes_submit_callbackhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#element_validatehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#descriptionhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#default_valuehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#button_typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#attributeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#actionhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahahhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#after_buildhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#valhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#itemhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#markuphttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#hiddenhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#formhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#submithttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#image_buttonhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#buttonhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#weightvalhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#treehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#titlehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#themehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#suffixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#sizehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#rowshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#return_valuehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#requiredhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#prefixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#parentshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#optionshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#multiplehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#maxlengthhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#field_suffixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#field_prefixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#element_validatehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#disabledhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#descriptionhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#deltahttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#default_valuehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#colshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#collapsiblehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#collapsedhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#autocomplete_pathhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#attributeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#after_buildhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahahhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#accesshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textfieldhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textareahttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#selecthttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#radioshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#radiohttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#passwordhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#filehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#fieldsethttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#datehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#elementshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#element_default_valueshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#propertieshttp://api.drupal.org/api/file/developer/topics/forms_api.htmlhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6/sourcehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.htmlhttp://api.drupal.org/ -
8/8/2019 Form Reference
2/17
Default Values
Every element automatically has these default values (see _element_info):
q #description = NULL
q #attributes = array()
q #required = FALSE q #tree = FALSE
q #parents = array()
The following is a list of default values which do not need to be set (found in system_elements):
q button
r #name = 'op'
r #button_type = 'submit'
r #executes_submit_callback = FALSE
r #ahah['event'] = 'click'
q checkbox
r #return_value = 1
r #ahah['event'] = 'change'
q checkboxes
r #tree = 1
q fieldset
r #collapsible = FALSE
r #collapsed = FALSE
q file
r #size = 6 0
q form
r #method = 'post'
r #action = request_uri ()
q image_button
r #button_type = 'submit' r #executes_submit_callback = TRUE
r #ahah['event'] = 'click' q item
r #prefix = ''
r #suffix = '' q markup
r #prefix = ''
r #suffix = ''
q radio
r #ahah['event'] = 'change'
q password
r #size = 3 0
r #maxlength = 6 4
r #ahah['event'] = 'blur'
q submit
r #name = 'op' r #button_type = 'submit'
r #executes_submit_callback = TRUE
r #ahah['event'] = 'click'
q textarea
r #cols = 6 0
r #rows = 5
r #ahah['event'] = 'blur'
q textfield
r #size = 6 0
r #maxlength = 128
r #autocomplete_path = FALSE
r #ahah['event'] = 'blur'
q weight
r
#delta = 1 0
#src - X - - - - - -
#submit X X X X - - - -
#suffix X X X X X X X -
#theme X X X X X X X -
#title - - - - - - X -
#tree X X X X X - - X
#validate X X X X - - - -
#value X X X - - X X X
#weight X X X - - X X -
http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#weightvalhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#valuehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#validatehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#treehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#titlehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#themehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#suffixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html##submithttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#srchttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#deltahttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#weighthttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#autocomplete_pathhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#maxlengthhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#sizehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textfieldhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#rowshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#colshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textareahttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#executes_submit_callbackhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#button_typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#namehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#submithttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#maxlengthhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#sizehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#passwordhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#radiohttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#suffixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#prefixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#markuphttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#suffixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#prefixhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#itemhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#executes_submit_callbackhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#button_typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#image_buttonhttp://api.drupal.org/api/function/request_uri/6http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#actionhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#methodhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#formhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#sizehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#filehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#collapsedhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#collapsiblehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#fieldsethttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#treehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#return_valuehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_eventhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#executes_submit_callbackhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#button_typehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#namehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#buttonhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#parentshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#treehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#requiredhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#attributeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#description -
8/8/2019 Form Reference
3/17
-
8/8/2019 Form Reference
4/17
file
Description : Format a file upload field.
Note: you will need to include $form['#attributes'] = array('enctype' => "multipart/form-data"); in your form. See this handbook page for anexample http:/ / drupal.org/ node/ 111782 .
Note: the #required property is not supported (setting it to true will always cause a validation error). Instead, you may want to use your ownvalidation function to do checks on the $_FILES array with #required set to false. You will also have to add your own required asterisk if youwould like one.
Properties : #attributes , #description , #prefix , #size (default: 60), #suffix , #title , #type . #weight
Usage example ( upload.module ):
form
Description : A form containing form elements
Properties : #action (default: request_uri ()), #attributes , #method (default: 'post'), #prefix , #submit , #suffix , #theme , #valid
Usage example :
N/A
hidden
Description : Store data in a hidden form field.
Properties : #prefix , #suffix , #type , #value
Usage example ( block.module ):
image_button
Description : Format a form submit button with an image.
Properties : #ahah , #attributes , #button_type (default: 'submit'), #executes_submit_callback (default: TRUE), #name (default: 'o#prefix , #src , #suffix , #submit , #type . #value , #weight
markup
Description : Generate generic markup for display inside forms. Note that there is no need to declare a form element as #type = 'markup'as this is the default type.
Note: if you use markup, if your content is not wrapped in tags (generally
or ), your content will fall outside of collapsed fieldsets.
Properties : #attributes , #prefix (default: ''), #suffix (default: ''), #type . #value , #weight
Usage example ( contact.module ):
item
Description : Generate a display-only form element allowing for an optional title and description.
No te: sin ce this is a r ead-only field, setting the #required property will do nothing except theme the form element to look as if it were actuallyrequired (i.e. by placing a red star next to the #title ).
Properties : #description , #prefix (default: ''), #required , #suffix (default: ''), #title , #type , #value , #weight
Usage example ( contact.module ):
-
8/8/2019 Form Reference
5/17
); ?>
password
Description : Format a single-line text field that does not display its contents visibly.
Properties : #ahah , #attributes , #description , #maxlength (default: 30), #prefix , #required , #size (default: 64), #suffix , #title#type . #weight
Usage example ( user.module ):
radio
Description : Format a radio button.
Properties : #ahah , #attributes , #default_value , #description , #prefix , #required , #suffix , #title , #type . #weight
Usage example :
N/A
radios
Description : Format a set of radio buttons.
Properties : #attributes , #default_value , #description , #options , #prefix , #required , #suffix , #title , #type . #weight
Usage example ( comment.module ):
select
Description : Format a drop-down menu or scrolling selection box.
Properties : #ahah , #attributes , #default_value , #description , #multiple , #options , #prefix , #required , #suffix , #title , #type#weight
Usage example ( system.module ):
submit
Description : Format a form submit button.Properties : #ahah , #attributes , #button_type (default: 'submit'), #executes_submit_callback (default: TRUE), #name (default: 'o# prefix , #s u f fi x , # ty p e . #v alue , # w ei gh t
Usage example ( locale.module ):
textarea
Descripti on : Format a multiple -l ine text field.
Properties : #ahah , #attributes , #cols (default: 60), #default_value , #description , #prefix , #required , #suffix , #title , #type(default: 5), #weight
Usage example ( forum.module ):
-
8/8/2019 Form Reference
6/17
'#type' => 'textarea' , '#title' => t ( 'Body' ), '#default_value' => $node -> body , '#required' => TRUE
); ?>
textfield
Description : Format a single-line text field.
Properties : #ahah , #attributes , #autocomplete_path (default: FALSE), #default_value , #description , #field_prefix , #field_suf#maxlength (default: 128), #prefix , #required , #size (default: 60), #suffix , #title , #type . #weight
Usage example ( forum.module ):
value
Description : A form value that is internal to the form and never displayed to the screen.
Properties : #type , #value
Usage example ( node.module ):
weight
Description : Format a weight selection menu.
Properties : #attributes , #delta (default: 10), #default_value , #description , #prefix , #required , #suffix , #title , #type . #weigh
Usage example ( menu.module ):
-
8/8/2019 Form Reference
7/17
'#description' => t ( 'A file system path where the files will be stored. This directory has to exist and be writable by Drupal. If thedownload method is set to public this directory has to be relative to Drupal installation directory, and be accessible over the web.When download method is set to private this directory should not be accessible over the web. Changing this location after the site hasbeen in use will cause problems so only change this setting on an existing site if you know what you are doing.' ), ); $form [ '#after_build' ] = array( 'system_check_directory' );
...
function system_check_directory ( $form_element , &$form_state ) { file_check_directory ( $form_element [ '#value' ], FILE_CREATE_DIRECTORY, $form_element [ '#parents' ][ 0]); return $form_element ;
} ?>
Property names without # signs causes havoc.
#ahah
Used by : button , checkbox , image button , password , radio , select , submit , textarea , textfield
An array of elements whose values control the behavior of the element with respect to the Drupal AHAH javascript methods.
The #ahah name refers to AHAH javascript replacement (Asychronous HTML and HTTP), a relative of AJAX. AHAH is a form of javascriptpage replacement that is both easy and straight forward. In a nutshell an AHAH request follows these steps:
1. Drupal builds a form element with a set of #ahah properties. The misc/ahah.js file is included on the page automatically.
2. ahah.js finds all the form elements on the page that have an #ahah[ 'path'] set and adds an event handler for the #ahah['event']on that form element.
3 . When the #ahah['event'] occurs on the element (such as 'click'), the AHAH request is made to the Drupal path of the element's['path'] .
4. Drupal generates HTML in a second request in the background. While the user waits for the callback to execute a throbber or progress baris shown as determined by #ahah[ 'progress '] . The result is returned to the original page containing the form element.
5. ahah.js gets the result and inserts the returned HTML into the #ahah[ 'wrapper '] . Depending on the #ahah['method'] , the result maffect the wrapper in different ways.
#ahah['effect']
Description : Specifies the effect used when adding the content from an AHAH request.
Values : String. Possible values: 'none' (default), 'fade', 'slide'. If the interface elements library is installed, any effect with the nameeffect Toggle may also be used.
Usage example ( poll.module ):
$form [ 'choice_wrapper' ][ 'poll_more' ] = array( '#type' => 'submit' , '#value' => t ( 'More choices' ), '#description' => t ( "If the amount of boxes above isn't enough, click here to add more choices." ), '#weight' => 1, '#submit' => array( 'poll_more_choices_submit' ), // If no javascript action. '#ahah' => array(
'path' => 'poll/js' , 'wrapper' => 'poll-choices' , 'method' => 'replace' ,
'effect' => 'fade' , ),
#ahah['event']
Description : When this event occurs to this element, Drupal will perform an HTTP request in the background via Javascript.
Values : String. Possible values: 'click', 'blur', 'change'. Note that #ahah['event'] does not need to be explicitly specified. Although it can bemanuall y set, u sually the default value will be sufficient.
#ahah['method']
Description : Modify the behavior of the returned HTML from an AHAH request when inserting into the #ahah_wrapper . If not set, thereturned HTML will replace the contents of the wrapper element, but it's also possible to use any of the available jQuery operations for DOmanipulation .
Values : String. Possible values: 'replace' (default), 'after', 'append', 'before', ' prepend'.
#ahah['path']
Description : If set, this property triggers AHAH behaviors on a form element. This is the Drupal menu path to a callback function which willgenerate HTML and return the string of HTML to Drupal. The result will be placed in the div specified in #ahah[ 'wrapper '] .
Values : String containing a Drupal menu path.
Usage example ( upload.module ):
-
8/8/2019 Form Reference
8/17
...
function _upload_form ( $node ) { ...
$form [ 'new' ][ 'attach' ] = array( '#type' => 'submit' , '#value' => t ( 'Attach' ), '#name' => 'attach' , '#ahah' => array(
'path' => 'upload/js' , 'wrapper' => 'attach-wrapper' , 'progress' => array( 'type' => 'bar' , 'message' => t ( 'Please wait...' )),
), '#submit' => array( 'node_form_submit_build_node' ),
); ...
return $form ; ?>
#ahah['path'] is set to 'upload/js', which has a menu item defined in the same module. Then the menu hook will call the 'upload_js' function which
generates HTML and returns it to original page.
#ahah['progress']
Description : Choose either a throbber or progress bar that is displayed while awaiting a response from the callback, and add an optional message.
Values : Array.
Possible keys: 'type', 'message', 'url', 'interval'
Possible values:
q #ahah[ 'progress '][ ' type'] String. Possible values: 'throbber' (default), 'bar'.q #ahah['progress']['message'] String. An optional message to the user; should be wrapped with t ().
q #ahah['progress']['url'] String. The optional callback path to use to determine how full the progress bar is (as defined in progress.js). Onlyuseable when 'type' is 'progress'.
q #ahah[ 'progress '][ ' interval '] String. The iterval to be used in updating the progress bar (as defined in progress.js). Ony used if 'url
defined and 'type' is 'progress'.
Usage example : see above useage in upload.module
#ahah['wrapper']
Description : This property defines the HTML id attribute of an element on the page will server as the destination for HTML returned by an AHAHrequest. Usually, a div element is used as the wrapper, as it provides the most flexibility for placement of elements before, after, or inside of it'sHTML tags. Th is property is required for using AHAH requests in on a form element.
Values : String containg a valid id attribute of an HTML element on the same page.
Usage example ( upload.module ):
$form [ 'new' ][ 'attach' ] = array( '#type' => 'submit' , '#value' => t ( 'Attach' ), '#name' => 'attach' , '#ahah' => array(
'path' => 'upload/js' , 'wrapper' => 'attach-wrapper' , 'progress' => array( 'type' => 'bar' , 'message' => t ( 'Please wait...' )),
), '#submit' => array( 'node_form_submit_build_node' ),
);
#attributes
Used by : button , checkbox , checkboxes , date , fieldset , file , form , markup , password , radio , radios , select , submit , textarea ,weight
Description : Additional HTML attributes, such as 'class' can be set using this mechanism.
Valu es : Any HTML attribute not covered by other properties, e.g. class (for control types), enctype (for forms).
Usage example ( search.module ):
The # is mandatory before property names.
#autocomplete_path
Use d b y : t extf ield
Description : The path the AJAX autocomplete script uses as the source for autocompletion.
Usage example ( node.module ):
http://api.drupal.org/api/file/modules/upload/upload.module/6http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#datehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#fieldsethttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#filehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#formhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#formhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#markuphttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#passwordhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#passwordhttp://api.drupal.org/api/file/modules/node/node.module/6http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textfieldhttp://api.drupal.org/api/file/modules/search/search.module/6http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#weighthttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#textareahttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#submithttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#selecthttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#radioshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#radiohttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#passwordhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#markuphttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#formhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#filehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#fieldsethttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#datehttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxeshttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#checkboxhttp://api.drupal.org/api/file/developer/topics/forms_api_reference.html#buttonhttp://api.drupal.org/api/file/modules/upload/upload.module/6http://api.drupal.org/api/file/modules/upload/upload.module/6http://api.drupal.org/api/file/developer/topics/forms_api_reference.html#ahah_pathhttp://api.drupal.org/api/function/t/6 -
8/8/2019 Form Reference
9/17
It's very important that you do not forget the # before property names.
#built
Used by : form
Description : Used to ascertain whether or not a form element has been built yet.
Values : TRUE or FALSE
Usage example : INTERNAL. See the _form_builder function in form.inc .
The first character of property names is #.
#button_type
Used by : button , submit
Description : Indicates CSS class to use for button( form- but ton_ type )
Values : submit, ???
Usage example : ( system.module ):
Developers should take care to not forget the first # character in property names.
#collapsed
Used by : fieldset
Description : Indicates whether or not the fieldset is collapsed by default. See #collapsible property.
Values : TRUE or FALSE
Usage example ( block.module ) :
Child names do not have a # as first char, but property names do.
#collapsible
Used by : fieldset
Description : Indicates whether or not the fieldset can be collapsed with JavaScript. See #collapsed property.
Values : TRUE or FALSE
Usage example ( block.module ):
One of the most important things about form API is not forgetting the # where it's appropriate.
#cols
Used by : textarea
Description : How many columns wide the textarea should be (see also #rows )
Values : A positive number
Usage example ( aggregator.module ):
-
8/8/2019 Form Reference
10/17
'#rows' => 5, ); ?>
The first # lets form API decide between a property name and a child.
#default_value
Used by : button , checkbox , checkboxes , date , file , markup , password , radio , radios , select , submit , textarea , textfield , weigh
Description : The value of the form element that will be displayed or selected initially if the form has not been submitted yet. Should NOTconfused with #value , which is a hard-coded value the user cannot change!
Values : Mixed
Usage example ( forum.module ):
How many different forms of warnings can I figure out to tell you that the first # in property names are important?
#delta
Used by : weight
Description : Number of weights to have selectable. For example, with $delta => 10, the weight selection box would display numbers from -10 to 10 .
Values : A positive number
Usage example ( menu.module ):
-
8/8/2019 Form Reference
11/17
function myelement_validate ( $element , & $form_state ) { if (empty( $element [ '#value' ]) {
form_error ( $element , t ( 'This field is required.' )); }
}
Usage example ( filter.module ):
While #element_validate makes sure that user data is valid, nothing validates the form for missing # in the beginning of property name.
#error
INTERNAL. Indicates whether or not a form element has been flagged as having an error.
#executes_submit_callback
Used by : button , submit , image_button
Description : Indicates whether or not button should submit the form.
Values : TRUE or FALSE
#id
INTERNAL. Used to populate form elements' id property.
#input
INTERNAL. Indicates whether or not input is possible for this form element.
#field_prefix
Used by : textfield
Description : Text or code that is placed directly in front of the textfield. This can be used to prefix a textfield with a constant string.
Values : Mixed
Usage example ( system.module ):
-
8/8/2019 Form Reference
12/17
You can spare lots of debug time by not forgetting the # in the beginning of property names.
#method
Used by : form
Description : The HTTP method with which the form will be submitted.
Values : GET or POST. Default is POST.
Usage example ( node.module ):
#multiple
Used by : select
Description : Indicates whether the user may select more than one item.
Values : TRUE or FALSE
Usage example ( taxonomy.module ):
By now, you probably know that the first character of property names is # but I thought some repetition can't hurt.
#name
INTERNAL. Refers to the name of an element ('foo' in $form['foo'])
#options
Used by : checkboxes , radios , select
Description : Selectable options for a form element that allows multiple choices.
Values : An array in the form of array(t('Display value 1'), tttt ('Display value 2')) or array('return_value1' => tttt ('Display Value 1'),'return_value2' => tttt ('Display Value 2')) if specific return values are required.
Usage example ( comment.module ):
If you are fed up with comments about # being the first character of property names, then sorry, but it's important.
#parents
Used by : All
Description : Identifies parent form elements. See #tree and #parents in the handbook.
Values : An array of element names.
Usage example ( comment.module ):
-
8/8/2019 Form Reference
13/17
); ?>
While the first character of the words parents and property is P, the first character of every property is #.
#prefix
Used by : button , checkbox , checkboxes , date , fieldset , file , form , hidden , markup , password , radio , radios , select , submit , tetextfield , weight
Description : Text or markup to include before the form element. Also see #suffix .
Values : Mixed
Usage example ( poll.module ):
-
8/8/2019 Form Reference
14/17
'#required' => TRUE, ); ?>
You know what's absolutely required? The # in the beginning of property names.
#return_value
Used by : checkbox , checkboxes , radio , radios
Description : Value element should return when selected
Values : Mixed
Usage example ( poll.module ):
-
8/8/2019 Form Reference
15/17
'#title' => t ( 'Parent item' ), '#default_value' => $default , '#options' => $options , '#attributes' => array( 'class' => 'menu-title-select' ),
); $form [ '#submit' ][] = 'menu_node_form_submit' ;
} ?>
Usage example ( menu.module ):
#suffix
Used by : button , checkbox , checkboxes , date , fieldset , file , form , hidden , markup , password , radio , radios , select , submit , tetextfield , weight
Description : Text or markup to include after the form element. Also see #prefix .
Values : Mixed
Usage example ( poll.module ):
-
8/8/2019 Form Reference
16/17
'#tree' => TRUE, ); $required = array( 'block' , 'filter' , 'system' , 'user' , 'watchdog' ); foreach ( $required as $require ) {
$form [ 'status' ][ $require ] = array( '#type' => 'hidden' ,
'#value' => 1, '#suffix' => t ( 'required' ),
); } ?>
#type
Used by : All
Description : Used to determine the type of form element.
Values : button , checkbox , checkboxes , date , fieldset , file , form , hidden , markup , password , radio , radios , select , submit , texttextfield , value , weight
Usage example ( locale.module ):
#validate
Used by : button , form , submit , image_button
Description : A list of custom validation functions that need to be passed.This is usually used to add additional vlidation functions to a form, or touse an alternate function rather than the default form validation function which is the form ID with _validate appended to it.
Values : An array of function names. Each such function will take $form and $form_state as parameters and should use form_set_error (form values do not pass validation. For example:
function test_form_validate ( $form , &$form_state ) { if ( $form_state['values'] [ 'name' ] == '' ) {
form_set_error ( 'name' , t ( 'You must select a name for this group of settings.' )); }
}
Usage example ( node.module ):
-
8/8/2019 Form Reference
17/17
urce code and documentation on this site is released under the terms of the GNU General Public License, version 2 and later . Drupal is a registtrademark of Dries Buytaert .
'#title' => t ( 'Parent' ), '#default_value' => ( $node -> parent ? $node -> parent : arg ( 4)), '#options' => book_toc ( $node -> nid ), '#weight' => - 15 , '#description' => t ( 'The parent that this page belongs in. Note that pages whose parent is are regarded as independent,
top-level books.' ), ); ?>
http://buytaert.net/http://api.drupal.org/api/file/LICENSE.txt