1. 7 includes/form.inc
  2. 4.7 includes/form.inc
  3. 5 includes/form.inc
  4. 6 includes/form.inc
  5. 8 core/includes/form.inc

File

includes/form.inc
View source
  1. <?php
  2. /**
  3. * @defgroup form Form generation
  4. * @{
  5. * Functions to enable the processing and display of HTML forms.
  6. *
  7. * Drupal uses these functions to achieve consistency in its form processing and
  8. * presentation, while simplifying code and reducing the amount of HTML that
  9. * must be explicitly generated by modules.
  10. *
  11. * The drupal_get_form() function handles retrieving, processing, and
  12. * displaying a rendered HTML form for modules automatically. For example:
  13. *
  14. * @code
  15. * // Display the user registration form.
  16. * $output = drupal_get_form('user_register');
  17. * @endcode
  18. *
  19. * Forms can also be built and submitted programmatically without any user input
  20. * using the drupal_execute() function.
  21. *
  22. * For information on the format of the structured arrays used to define forms,
  23. * and more detailed explanations of the Form API workflow, see the
  24. * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/5 reference @endlink
  25. * and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html/5 quickstart guide. @endlink
  26. */
  27. /**
  28. * Retrieves a form from a builder function, passes it on for
  29. * processing, and renders the form or redirects to its destination
  30. * as appropriate. In multi-step form scenarios, it handles properly
  31. * processing the values using the previous step's form definition,
  32. * then rendering the requested step for display.
  33. *
  34. * @param $form_id
  35. * The unique string identifying the desired form. If a function
  36. * with that name exists, it is called to build the form array.
  37. * Modules that need to generate the same form (or very similar forms)
  38. * using different $form_ids can implement hook_forms(), which maps
  39. * different $form_id values to the proper form building function. Examples
  40. * may be found in node_forms(), search_forms(), and user_forms().
  41. * @param ...
  42. * Any additional arguments needed by the form building function.
  43. * @return
  44. * The rendered form.
  45. */
  46. function drupal_get_form($form_id) {
  47. // In multi-step form scenarios, the incoming $_POST values are not
  48. // necessarily intended for the current form. We need to build
  49. // a copy of the previously built form for validation and processing,
  50. // then go on to the one that was requested if everything works.
  51. $form_build_id = md5(mt_rand());
  52. if (isset($_POST['form_build_id']) && isset($_SESSION['form'][$_POST['form_build_id']]['args']) && $_POST['form_id'] == $form_id) {
  53. // There's a previously stored multi-step form. We should handle
  54. // IT first.
  55. $stored = TRUE;
  56. $args = $_SESSION['form'][$_POST['form_build_id']]['args'];
  57. $form = call_user_func_array('drupal_retrieve_form', $args);
  58. $form['#build_id'] = $_POST['form_build_id'];
  59. }
  60. else {
  61. // We're coming in fresh; build things as they would be. If the
  62. // form's #multistep flag is set, store the build parameters so
  63. // the same form can be reconstituted for validation.
  64. $args = func_get_args();
  65. $form = call_user_func_array('drupal_retrieve_form', $args);
  66. if (isset($form['#multistep']) && $form['#multistep']) {
  67. // Clean up old multistep form session data.
  68. _drupal_clean_form_sessions();
  69. $_SESSION['form'][$form_build_id] = array('timestamp' => time(), 'args' => $args);
  70. $form['#build_id'] = $form_build_id;
  71. }
  72. $stored = FALSE;
  73. }
  74. // Process the form, submit it, and store any errors if necessary.
  75. drupal_process_form($args[0], $form);
  76. if ($stored && !form_get_errors()) {
  77. // If it's a stored form and there were no errors, we processed the
  78. // stored form successfully. Now we need to build the form that was
  79. // actually requested. We always pass in the current $_POST values
  80. // to the builder function, as values from one stage of a multistep
  81. // form can determine how subsequent steps are displayed.
  82. $args = func_get_args();
  83. $args[] = $_POST;
  84. $form = call_user_func_array('drupal_retrieve_form', $args);
  85. unset($_SESSION['form'][$_POST['form_build_id']]);
  86. if (isset($form['#multistep']) && $form['#multistep']) {
  87. $_SESSION['form'][$form_build_id] = array('timestamp' => time(), 'args' => $args);
  88. $form['#build_id'] = $form_build_id;
  89. }
  90. drupal_prepare_form($args[0], $form);
  91. }
  92. return drupal_render_form($args[0], $form);
  93. }
  94. /**
  95. * Remove form information that's at least a day old from the
  96. * $_SESSION['form'] array.
  97. */
  98. function _drupal_clean_form_sessions() {
  99. if (isset($_SESSION['form'])) {
  100. foreach ($_SESSION['form'] as $build_id => $data) {
  101. if ($data['timestamp'] < (time() - 84600)) {
  102. unset($_SESSION['form'][$build_id]);
  103. }
  104. }
  105. }
  106. }
  107. /**
  108. * Retrieves a form using a form_id, populates it with $form_values,
  109. * processes it, and returns any validation errors encountered. This
  110. * function is the programmatic counterpart to drupal_get_form().
  111. *
  112. * @param $form_id
  113. * The unique string identifying the desired form. If a function
  114. * with that name exists, it is called to build the form array.
  115. * Modules that need to generate the same form (or very similar forms)
  116. * using different $form_ids can implement hook_forms(), which maps
  117. * different $form_id values to the proper form building function. Examples
  118. * may be found in node_forms(), search_forms(), and user_forms().
  119. * @param $form_values
  120. * An array of values mirroring the values returned by a given form
  121. * when it is submitted by a user.
  122. * @param ...
  123. * Any additional arguments needed by the form building function.
  124. * @return
  125. * Any form validation errors encountered.
  126. *
  127. * For example:
  128. *
  129. * // register a new user
  130. * $values['name'] = 'robo-user';
  131. * $values['mail'] = 'robouser@example.com';
  132. * $values['pass'] = 'password';
  133. * drupal_execute('user_register', $values);
  134. *
  135. * // Create a new node
  136. * $node = array('type' => 'story');
  137. * $values['title'] = 'My node';
  138. * $values['body'] = 'This is the body text!';
  139. * $values['name'] = 'robo-user';
  140. * drupal_execute('story_node_form', $values, $node);
  141. */
  142. function drupal_execute($form_id, $form_values) {
  143. $args = func_get_args();
  144. $form_id = array_shift($args);
  145. $form_values = array_shift($args);
  146. array_unshift($args, $form_id);
  147. if (isset($form_values)) {
  148. $form = call_user_func_array('drupal_retrieve_form', $args);
  149. $form['#post'] = $form_values;
  150. return drupal_process_form($form_id, $form);
  151. }
  152. }
  153. /**
  154. * Retrieves the structured array that defines a given form.
  155. *
  156. * @param $form_id
  157. * The unique string identifying the desired form. If a function
  158. * with that name exists, it is called to build the form array.
  159. * Modules that need to generate the same form (or very similar forms)
  160. * using different $form_ids can implement hook_forms(), which maps
  161. * different $form_id values to the proper form building function.
  162. * @param ...
  163. * Any additional arguments needed by the form building function.
  164. */
  165. function drupal_retrieve_form($form_id) {
  166. static $forms;
  167. // We save two copies of the incoming arguments: one for modules to use
  168. // when mapping form ids to builder functions, and another to pass to
  169. // the builder function itself. We shift out the first argument -- the
  170. // $form_id itself -- from the list to pass into the builder function,
  171. // since it's already known.
  172. $args = func_get_args();
  173. $saved_args = $args;
  174. array_shift($args);
  175. // We first check to see if there's a function named after the $form_id.
  176. // If there is, we simply pass the arguments on to it to get the form.
  177. if (!function_exists($form_id)) {
  178. // In cases where many form_ids need to share a central builder function,
  179. // such as the node editing form, modules can implement hook_forms(). It
  180. // maps one or more form_ids to the correct builder functions.
  181. //
  182. // We cache the results of that hook to save time, but that only works
  183. // for modules that know all their form_ids in advance. (A module that
  184. // adds a small 'rate this comment' form to each comment in a list
  185. // would need a unique form_id for each one, for example.)
  186. //
  187. // So, we call the hook if $forms isn't yet populated, OR if it doesn't
  188. // yet have an entry for the requested form_id.
  189. if (!isset($forms) || !isset($forms[$form_id])) {
  190. $forms = module_invoke_all('forms', $saved_args);
  191. }
  192. $form_definition = $forms[$form_id];
  193. if (isset($form_definition['callback arguments'])) {
  194. $args = array_merge($form_definition['callback arguments'], $args);
  195. }
  196. if (isset($form_definition['callback'])) {
  197. $callback = $form_definition['callback'];
  198. }
  199. }
  200. // If $callback was returned by a hook_forms() implementation, call it.
  201. // Otherwise, call the function named after the form id.
  202. $form = call_user_func_array(isset($callback) ? $callback : $form_id, $args);
  203. // We store the original function arguments, rather than the final $arg
  204. // value, so that form_alter functions can see what was originally
  205. // passed to drupal_retrieve_form(). This allows the contents of #parameters
  206. // to be saved and passed in at a later date to recreate the form.
  207. $form['#parameters'] = $saved_args;
  208. return $form;
  209. }
  210. /**
  211. * This function is the heart of form API. The form gets built, validated and in
  212. * appropriate cases, submitted.
  213. *
  214. * @param $form_id
  215. * The unique string identifying the current form.
  216. * @param $form
  217. * An associative array containing the structure of the form.
  218. * @return
  219. * The path to redirect the user to upon completion.
  220. */
  221. function drupal_process_form($form_id, &$form) {
  222. global $form_values, $form_submitted, $user, $form_button_counter;
  223. static $saved_globals = array();
  224. // In some scenarios, this function can be called recursively. Pushing any pre-existing
  225. // $form_values and form submission data lets us start fresh without clobbering work done
  226. // in earlier recursive calls.
  227. array_push($saved_globals, array($form_values, $form_submitted, $form_button_counter));
  228. $form_values = array();
  229. $form_submitted = FALSE;
  230. $form_button_counter = array(0, 0);
  231. drupal_prepare_form($form_id, $form);
  232. if (($form['#programmed']) || (!empty($_POST) && (($_POST['form_id'] == $form_id)))) {
  233. drupal_validate_form($form_id, $form);
  234. // IE does not send a button value when there is only one submit button (and no non-submit buttons)
  235. // and you submit by pressing enter.
  236. // In that case we accept a submission without button values.
  237. if ((($form['#programmed']) || $form_submitted || (!$form_button_counter[0] && $form_button_counter[1])) && !form_get_errors()) {
  238. $redirect = drupal_submit_form($form_id, $form);
  239. if (!$form['#programmed']) {
  240. drupal_redirect_form($form, $redirect);
  241. }
  242. }
  243. }
  244. // We've finished calling functions that alter the global values, so we can
  245. // restore the ones that were there before this function was called.
  246. list($form_values, $form_submitted, $form_button_counter) = array_pop($saved_globals);
  247. return $redirect;
  248. }
  249. /**
  250. * Prepares a structured form array by adding required elements,
  251. * executing any hook_form_alter functions, and optionally inserting
  252. * a validation token to prevent tampering.
  253. *
  254. * @param $form_id
  255. * A unique string identifying the form for validation, submission,
  256. * theming, and hook_form_alter functions.
  257. * @param $form
  258. * An associative array containing the structure of the form.
  259. */
  260. function drupal_prepare_form($form_id, &$form) {
  261. global $user;
  262. $form['#type'] = 'form';
  263. if (!isset($form['#post'])) {
  264. $form['#post'] = $_POST;
  265. $form['#programmed'] = FALSE;
  266. }
  267. else {
  268. $form['#programmed'] = TRUE;
  269. }
  270. // In multi-step form scenarios, this id is used to identify
  271. // a unique instance of a particular form for retrieval.
  272. if (isset($form['#build_id'])) {
  273. $form['form_build_id'] = array(
  274. '#type' => 'hidden',
  275. '#value' => $form['#build_id'],
  276. '#id' => $form['#build_id'],
  277. '#name' => 'form_build_id',
  278. );
  279. }
  280. // If $base is set, it is used in place of $form_id when constructing validation,
  281. // submission, and theming functions. Useful for mapping many similar or duplicate
  282. // forms with different $form_ids to the same processing functions.
  283. if (isset($form['#base'])) {
  284. $base = $form['#base'];
  285. }
  286. // Add a token, based on either #token or form_id, to any form displayed to
  287. // authenticated users. This ensures that any submitted form was actually
  288. // requested previously by the user and protects against cross site request
  289. // forgeries.
  290. if (isset($form['#token'])) {
  291. if ($form['#token'] === FALSE || $user->uid == 0 || $form['#programmed']) {
  292. unset($form['#token']);
  293. }
  294. else {
  295. $form['form_token'] = array('#type' => 'token', '#default_value' => drupal_get_token($form['#token']));
  296. }
  297. }
  298. else if ($user->uid && !$form['#programmed']) {
  299. $form['#token'] = $form_id;
  300. $form['form_token'] = array(
  301. '#id' => form_clean_id('edit-'. $form_id .'-form-token'),
  302. '#type' => 'token',
  303. '#default_value' => drupal_get_token($form['#token']),
  304. );
  305. }
  306. if (isset($form_id)) {
  307. $form['form_id'] = array('#type' => 'hidden', '#value' => $form_id, '#id' => form_clean_id("edit-$form_id"));
  308. }
  309. if (!isset($form['#id'])) {
  310. $form['#id'] = form_clean_id($form_id);
  311. }
  312. $form += _element_info('form');
  313. if (!isset($form['#validate'])) {
  314. if (function_exists($form_id .'_validate')) {
  315. $form['#validate'] = array($form_id .'_validate' => array());
  316. }
  317. elseif (function_exists($base .'_validate')) {
  318. $form['#validate'] = array($base .'_validate' => array());
  319. }
  320. }
  321. if (!isset($form['#submit'])) {
  322. if (function_exists($form_id .'_submit')) {
  323. // We set submit here so that it can be altered.
  324. $form['#submit'] = array($form_id .'_submit' => array());
  325. }
  326. elseif (function_exists($base .'_submit')) {
  327. $form['#submit'] = array($base .'_submit' => array());
  328. }
  329. }
  330. foreach (module_implements('form_alter') as $module) {
  331. $function = $module .'_form_alter';
  332. $function($form_id, $form);
  333. }
  334. $form = form_builder($form_id, $form);
  335. }
  336. /**
  337. * Validates user-submitted form data from a global variable using
  338. * the validate functions defined in a structured form array.
  339. *
  340. * @param $form_id
  341. * A unique string identifying the form for validation, submission,
  342. * theming, and hook_form_alter functions.
  343. * @param $form
  344. * An associative array containing the structure of the form.
  345. *
  346. */
  347. function drupal_validate_form($form_id, $form) {
  348. global $form_values;
  349. static $validated_forms = array();
  350. if (isset($validated_forms[$form_id])) {
  351. return;
  352. }
  353. // If the session token was set by drupal_prepare_form(), ensure that it
  354. // matches the current user's session.
  355. if (isset($form['#token'])) {
  356. if (!drupal_valid_token($form_values['form_token'], $form['#token'])) {
  357. // Setting this error will cause the form to fail validation.
  358. form_set_error('form_token', t('Validation error, please try again. If this error persists, please contact the site administrator.'));
  359. }
  360. }
  361. _form_validate($form, $form_id);
  362. $validated_forms[$form_id] = TRUE;
  363. }
  364. /**
  365. * Processes user-submitted form data from a global variable using
  366. * the submit functions defined in a structured form array.
  367. *
  368. * @param $form_id
  369. * A unique string identifying the form for validation, submission,
  370. * theming, and hook_form_alter functions.
  371. * @param $form
  372. * An associative array containing the structure of the form.
  373. * @return
  374. * A string containing the path of the page to display when processing
  375. * is complete.
  376. *
  377. */
  378. function drupal_submit_form($form_id, $form) {
  379. global $form_values;
  380. $default_args = array($form_id, &$form_values);
  381. $submitted = FALSE;
  382. $goto = NULL;
  383. if (isset($form['#submit'])) {
  384. foreach ($form['#submit'] as $function => $args) {
  385. if (function_exists($function)) {
  386. $args = array_merge($default_args, (array) $args);
  387. // Since we can only redirect to one page, only the last redirect
  388. // will work.
  389. $redirect = call_user_func_array($function, $args);
  390. $submitted = TRUE;
  391. if (isset($redirect)) {
  392. $goto = $redirect;
  393. }
  394. }
  395. }
  396. }
  397. return $goto;
  398. }
  399. /**
  400. * Renders a structured form array into themed HTML.
  401. *
  402. * @param $form_id
  403. * A unique string identifying the form for validation, submission,
  404. * theming, and hook_form_alter functions.
  405. * @param $form
  406. * An associative array containing the structure of the form.
  407. * @return
  408. * A string containing the path of the page to display when processing
  409. * is complete.
  410. *
  411. */
  412. function drupal_render_form($form_id, &$form) {
  413. // Don't override #theme if someone already set it.
  414. if (isset($form['#base'])) {
  415. $base = $form['#base'];
  416. }
  417. if (!isset($form['#theme'])) {
  418. if (theme_get_function($form_id)) {
  419. $form['#theme'] = $form_id;
  420. }
  421. elseif (theme_get_function($base)) {
  422. $form['#theme'] = $base;
  423. }
  424. }
  425. if (isset($form['#pre_render'])) {
  426. foreach ($form['#pre_render'] as $function) {
  427. if (function_exists($function)) {
  428. $function($form_id, $form);
  429. }
  430. }
  431. }
  432. $output = drupal_render($form);
  433. return $output;
  434. }
  435. /**
  436. * Redirect the user to a URL after a form has been processed.
  437. *
  438. * @param $form
  439. * An associative array containing the structure of the form.
  440. * @param $redirect
  441. * An optional string containing the destination path to redirect
  442. * to if none is specified by the form.
  443. *
  444. */
  445. function drupal_redirect_form($form, $redirect = NULL) {
  446. if (isset($redirect)) {
  447. $goto = $redirect;
  448. }
  449. if (isset($form['#redirect'])) {
  450. $goto = $form['#redirect'];
  451. }
  452. if ($goto !== FALSE) {
  453. if (is_array($goto)) {
  454. call_user_func_array('drupal_goto', $goto);
  455. }
  456. elseif (!isset($goto)) {
  457. drupal_goto($_GET['q']);
  458. }
  459. else {
  460. drupal_goto($goto);
  461. }
  462. }
  463. }
  464. /**
  465. * Performs validation on form elements. First ensures required fields are
  466. * completed, #maxlength is not exceeded, and selected options were in the
  467. * list of options given to the user. Then calls user-defined validators.
  468. *
  469. * @param $elements
  470. * An associative array containing the structure of the form.
  471. * @param $form_id
  472. * A unique string identifying the form for validation, submission,
  473. * theming, and hook_form_alter functions.
  474. */
  475. function _form_validate($elements, $form_id = NULL) {
  476. // Recurse through all children.
  477. foreach (element_children($elements) as $key) {
  478. if (isset($elements[$key]) && $elements[$key]) {
  479. _form_validate($elements[$key]);
  480. }
  481. }
  482. /* Validate the current input */
  483. if (!isset($elements['#validated']) || !$elements['#validated']) {
  484. if (isset($elements['#needs_validation'])) {
  485. // Make sure a value is passed when the field is required.
  486. // A simple call to empty() will not cut it here as some fields, like
  487. // checkboxes, can return a valid value of '0'. Instead, check the
  488. // length if it's a string, and the item count if it's an array.
  489. if ($elements['#required'] && (!count($elements['#value']) || (is_string($elements['#value']) && strlen(trim($elements['#value'])) == 0))) {
  490. form_error($elements, t('!name field is required.', array('!name' => $elements['#title'])));
  491. }
  492. // Verify that the value is not longer than #maxlength.
  493. if (isset($elements['#maxlength']) && drupal_strlen($elements['#value']) > $elements['#maxlength']) {
  494. form_error($elements, t('!name cannot be longer than %max characters but is currently %length characters long.', array('!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title'], '%max' => $elements['#maxlength'], '%length' => drupal_strlen($elements['#value']))));
  495. }
  496. // Add legal choice check if element has #options. Can be skipped, but
  497. // then you must validate your own element.
  498. if (isset($elements['#options']) && isset($elements['#value']) && !isset($elements['#DANGEROUS_SKIP_CHECK'])) {
  499. if ($elements['#type'] == 'select') {
  500. $options = form_options_flatten($elements['#options']);
  501. }
  502. else {
  503. $options = $elements['#options'];
  504. }
  505. if (is_array($elements['#value'])) {
  506. $value = $elements['#type'] == 'checkboxes' ? array_keys(array_filter($elements['#value'])) : $elements['#value'];
  507. foreach ($value as $v) {
  508. if (!isset($options[$v])) {
  509. form_error($elements, t('An illegal choice has been detected. Please contact the site administrator.'));
  510. watchdog('form', t('Illegal choice %choice in !name element.', array('%choice' => $v, '!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title'])), WATCHDOG_ERROR);
  511. }
  512. }
  513. }
  514. elseif (!isset($options[$elements['#value']])) {
  515. form_error($elements, t('An illegal choice has been detected. Please contact the site administrator.'));
  516. watchdog('form', t('Illegal choice %choice in %name element.', array('%choice' => $elements['#value'], '%name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title'])), WATCHDOG_ERROR);
  517. }
  518. }
  519. }
  520. // Call user-defined validators.
  521. if (isset($elements['#validate'])) {
  522. foreach ($elements['#validate'] as $function => $args) {
  523. $args = array_merge(array($elements), $args);
  524. // For the full form we hand over a copy of $form_values.
  525. if (isset($form_id)) {
  526. $args = array_merge(array($form_id, $GLOBALS['form_values']), $args);
  527. }
  528. if (function_exists($function)) {
  529. call_user_func_array($function, $args);
  530. }
  531. }
  532. }
  533. $elements['#validated'] = TRUE;
  534. }
  535. }
  536. /**
  537. * File an error against a form element. If the name of the element is
  538. * edit[foo][bar] then you may pass either foo or foo][bar as $name
  539. * foo will set an error for all its children.
  540. */
  541. function form_set_error($name = NULL, $message = '') {
  542. static $form = array();
  543. if (isset($name) && !isset($form[$name])) {
  544. $form[$name] = $message;
  545. if ($message) {
  546. drupal_set_message($message, 'error');
  547. }
  548. }
  549. return $form;
  550. }
  551. /**
  552. * Return an associative array of all errors.
  553. */
  554. function form_get_errors() {
  555. $form = form_set_error();
  556. if (!empty($form)) {
  557. return $form;
  558. }
  559. }
  560. /**
  561. * Return the error message filed against the form with the specified name.
  562. */
  563. function form_get_error($element) {
  564. $form = form_set_error();
  565. $key = $element['#parents'][0];
  566. if (isset($form[$key])) {
  567. return $form[$key];
  568. }
  569. $key = implode('][', $element['#parents']);
  570. if (isset($form[$key])) {
  571. return $form[$key];
  572. }
  573. }
  574. /**
  575. * Flag an element as having an error.
  576. */
  577. function form_error(&$element, $message = '') {
  578. $element['#error'] = TRUE;
  579. form_set_error(implode('][', $element['#parents']), $message);
  580. }
  581. /**
  582. * Adds some required properties to each form element, which are used
  583. * internally in the form API. This function also automatically assigns
  584. * the value property from the $edit array, provided the element doesn't
  585. * already have an assigned value.
  586. *
  587. * @param $form_id
  588. * A unique string identifying the form for validation, submission,
  589. * theming, and hook_form_alter functions.
  590. * @param $form
  591. * An associative array containing the structure of the form.
  592. */
  593. function form_builder($form_id, $form) {
  594. global $form_values, $form_submitted, $form_button_counter;
  595. // Initialize as unprocessed.
  596. $form['#processed'] = FALSE;
  597. /* Use element defaults */
  598. if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
  599. // Overlay $info onto $form, retaining preexisting keys in $form.
  600. $form += $info;
  601. }
  602. if (isset($form['#input']) && $form['#input']) {
  603. if (!isset($form['#name'])) {
  604. $name = array_shift($form['#parents']);
  605. $form['#name'] = $name;
  606. if ($form['#type'] == 'file') {
  607. // To make it easier to handle $_FILES in file.inc, we place all
  608. // file fields in the 'files' array. Also, we do not support
  609. // nested file names.
  610. $form['#name'] = 'files['. $form['#name'] .']';
  611. }
  612. elseif (count($form['#parents'])) {
  613. $form['#name'] .= '['. implode('][', $form['#parents']) .']';
  614. }
  615. array_unshift($form['#parents'], $name);
  616. }
  617. if (!isset($form['#id'])) {
  618. $form['#id'] = form_clean_id('edit-'. implode('-', $form['#parents']));
  619. }
  620. if (isset($form['#disabled']) && $form['#disabled']) {
  621. $form['#attributes']['disabled'] = 'disabled';
  622. }
  623. if (!isset($form['#value']) && !array_key_exists('#value', $form)) {
  624. if (($form['#programmed']) || ((!isset($form['#access']) || $form['#access']) && isset($form['#post']) && (isset($form['#post']['form_id']) && $form['#post']['form_id'] == $form_id))) {
  625. $edit = $form['#post'];
  626. foreach ($form['#parents'] as $parent) {
  627. $edit = isset($edit[$parent]) ? $edit[$parent] : NULL;
  628. }
  629. if (!$form['#programmed'] || isset($edit)) {
  630. switch ($form['#type']) {
  631. case 'checkbox':
  632. $form['#value'] = !empty($edit) ? $form['#return_value'] : 0;
  633. break;
  634. case 'select':
  635. if (isset($form['#multiple']) && $form['#multiple']) {
  636. if (isset($edit) && is_array($edit)) {
  637. $form['#value'] = drupal_map_assoc($edit);
  638. }
  639. else {
  640. $form['#value'] = array();
  641. }
  642. }
  643. elseif (isset($edit)) {
  644. $form['#value'] = $edit;
  645. }
  646. break;
  647. case 'textfield':
  648. if (isset($edit)) {
  649. // Equate $edit to the form value to ensure it's marked for
  650. // validation.
  651. $edit = str_replace(array("\r", "\n"), '', $edit);
  652. $form['#value'] = $edit;
  653. }
  654. break;
  655. case 'token':
  656. $form['#value'] = (string)$edit;
  657. break;
  658. default:
  659. if (isset($edit)) {
  660. $form['#value'] = $edit;
  661. }
  662. }
  663. // Mark all posted values for validation.
  664. if ((isset($form['#value']) && $form['#value'] === $edit) || (isset($form['#required']) && $form['#required'])) {
  665. $form['#needs_validation'] = TRUE;
  666. }
  667. }
  668. }
  669. if (!isset($form['#value'])) {
  670. $function = $form['#type'] . '_value';
  671. if (function_exists($function)) {
  672. $function($form);
  673. }
  674. else {
  675. $form['#value'] = isset($form['#default_value']) ? $form['#default_value'] : '';
  676. }
  677. }
  678. }
  679. if (isset($form['#executes_submit_callback'])) {
  680. // Count submit and non-submit buttons.
  681. $form_button_counter[$form['#executes_submit_callback']]++;
  682. // See if a submit button was pressed.
  683. if (isset($form['#post'][$form['#name']]) && $form['#post'][$form['#name']] == $form['#value']) {
  684. $form_submitted = $form_submitted || $form['#executes_submit_callback'];
  685. // In most cases, we want to use form_set_value() to manipulate the
  686. // global variables. In this special case, we want to make sure that
  687. // the value of this element is listed in $form_variables under 'op'.
  688. $form_values[$form['#name']] = $form['#value'];
  689. }
  690. }
  691. }
  692. // Allow for elements to expand to multiple elements, e.g., radios,
  693. // checkboxes and files.
  694. if (isset($form['#process']) && !$form['#processed']) {
  695. foreach ($form['#process'] as $process => $args) {
  696. if (function_exists($process)) {
  697. $args = array_merge(array($form), array($edit), $args);
  698. $form = call_user_func_array($process, $args);
  699. }
  700. }
  701. $form['#processed'] = TRUE;
  702. }
  703. // Set the $form_values key that gets passed to validate and submit.
  704. // We call this after #process gets called so that #process has a
  705. // chance to update #value if desired.
  706. if (isset($form['#input']) && $form['#input']) {
  707. form_set_value($form, $form['#value']);
  708. }
  709. // We start off assuming all form elements are in the correct order.
  710. $form['#sorted'] = TRUE;
  711. // Recurse through all child elements.
  712. $count = 0;
  713. foreach (element_children($form) as $key) {
  714. $form[$key]['#post'] = $form['#post'];
  715. $form[$key]['#programmed'] = $form['#programmed'];
  716. // Don't squash an existing tree value.
  717. if (!isset($form[$key]['#tree'])) {
  718. $form[$key]['#tree'] = $form['#tree'];
  719. }
  720. // Deny access to child elements if parent is denied.
  721. if (isset($form['#access']) && !$form['#access']) {
  722. $form[$key]['#access'] = FALSE;
  723. }
  724. // Don't squash existing parents value.
  725. if (!isset($form[$key]['#parents'])) {
  726. // Check to see if a tree of child elements is present. If so,
  727. // continue down the tree if required.
  728. $form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);
  729. }
  730. // Assign a decimal placeholder weight to preserve original array order.
  731. if (!isset($form[$key]['#weight'])) {
  732. $form[$key]['#weight'] = $count/1000;
  733. }
  734. else {
  735. // If one of the child elements has a weight then we will need to sort
  736. // later.
  737. unset($form['#sorted']);
  738. }
  739. $form[$key] = form_builder($form_id, $form[$key]);
  740. $count++;
  741. }
  742. if (isset($form['#after_build']) && !isset($form['#after_build_done'])) {
  743. foreach ($form['#after_build'] as $function) {
  744. if (function_exists($function)) {
  745. $form = $function($form, $form_values);
  746. }
  747. }
  748. $form['#after_build_done'] = TRUE;
  749. }
  750. return $form;
  751. }
  752. /**
  753. * Use this function to make changes to form values in the form validate
  754. * phase, so they will be available in the submit phase in $form_values.
  755. *
  756. * Specifically, if $form['#parents'] is array('foo', 'bar')
  757. * and $value is 'baz' then this function will make
  758. * $form_values['foo']['bar'] to be 'baz'.
  759. *
  760. * @param $form
  761. * The form item. Keys used: #parents, #value
  762. * @param $value
  763. * The value for the form item.
  764. */
  765. function form_set_value($form, $value) {
  766. global $form_values;
  767. _form_set_value($form_values, $form, $form['#parents'], $value);
  768. }
  769. /**
  770. * Helper function for form_set_value().
  771. *
  772. * We iterate over $parents and create nested arrays for them
  773. * in $form_values if needed. Then we insert the value into
  774. * the right array.
  775. */
  776. function _form_set_value(&$form_values, $form, $parents, $value) {
  777. $parent = array_shift($parents);
  778. if (empty($parents)) {
  779. $form_values[$parent] = $value;
  780. }
  781. else {
  782. if (!isset($form_values[$parent])) {
  783. $form_values[$parent] = array();
  784. }
  785. _form_set_value($form_values[$parent], $form, $parents, $value);
  786. }
  787. return $form;
  788. }
  789. /**
  790. * Retrieve the default properties for the defined element type.
  791. */
  792. function _element_info($type, $refresh = NULL) {
  793. static $cache;
  794. $basic_defaults = array(
  795. '#description' => NULL,
  796. '#attributes' => array(),
  797. '#required' => FALSE,
  798. '#tree' => FALSE,
  799. '#parents' => array()
  800. );
  801. if (!isset($cache) || $refresh) {
  802. $cache = array();
  803. foreach (module_implements('elements') as $module) {
  804. $elements = module_invoke($module, 'elements');
  805. if (isset($elements) && is_array($elements)) {
  806. $cache = array_merge_recursive($cache, $elements);
  807. }
  808. }
  809. if (sizeof($cache)) {
  810. foreach ($cache as $element_type => $info) {
  811. $cache[$element_type] = array_merge_recursive($basic_defaults, $info);
  812. }
  813. }
  814. }
  815. return $cache[$type];
  816. }
  817. function form_options_flatten($array, $reset = TRUE) {
  818. static $return;
  819. if ($reset) {
  820. $return = array();
  821. }
  822. foreach ($array as $key => $value) {
  823. if (is_object($value)) {
  824. form_options_flatten($value->option, FALSE);
  825. }
  826. else if (is_array($value)) {
  827. form_options_flatten($value, FALSE);
  828. }
  829. else {
  830. $return[$key] = 1;
  831. }
  832. }
  833. return $return;
  834. }
  835. /**
  836. * Format a dropdown menu or scrolling selection box.
  837. *
  838. * @param $element
  839. * An associative array containing the properties of the element.
  840. * Properties used: title, value, options, description, extra, multiple, required
  841. * @return
  842. * A themed HTML string representing the form element.
  843. *
  844. * It is possible to group options together; to do this, change the format of
  845. * $options to an associative array in which the keys are group labels, and the
  846. * values are associative arrays in the normal $options format.
  847. */
  848. function theme_select($element) {
  849. $select = '';
  850. $size = $element['#size'] ? ' size="' . $element['#size'] . '"' : '';
  851. _form_set_class($element, array('form-select'));
  852. $multiple = isset($element['#multiple']) && $element['#multiple'];
  853. return theme('form_element', $element, '<select name="'. $element['#name'] .''. ($multiple ? '[]' : '') .'"'. ($multiple ? ' multiple="multiple" ' : '') . drupal_attributes($element['#attributes']) .' id="'. $element['#id'] .'" '. $size .'>'. form_select_options($element) .'</select>');
  854. }
  855. function form_select_options($element, $choices = NULL) {
  856. if (!isset($choices)) {
  857. $choices = $element['#options'];
  858. }
  859. // array_key_exists() accommodates the rare event where $element['#value'] is NULL.
  860. // isset() fails in this situation.
  861. $value_valid = isset($element['#value']) || array_key_exists('#value', $element);
  862. $value_is_array = is_array($element['#value']);
  863. $options = '';
  864. foreach ($choices as $key => $choice) {
  865. if (is_array($choice)) {
  866. $options .= '<optgroup label="'. $key .'">';
  867. $options .= form_select_options($element, $choice);
  868. $options .= '</optgroup>';
  869. }
  870. elseif (is_object($choice)) {
  871. $options .= form_select_options($element, $choice->option);
  872. }
  873. else {
  874. $key = (string)$key;
  875. if ($value_valid && (!$value_is_array && (string)$element['#value'] === $key || ($value_is_array && in_array($key, $element['#value'])))) {
  876. $selected = ' selected="selected"';
  877. }
  878. else {
  879. $selected = '';
  880. }
  881. $options .= '<option value="'. check_plain($key) .'"'. $selected .'>'. check_plain($choice) .'</option>';
  882. }
  883. }
  884. return $options;
  885. }
  886. /**
  887. * Traverses a select element's #option array looking for any values
  888. * that hold the given key. Returns an array of indexes that match.
  889. *
  890. * This function is useful if you need to modify the options that are
  891. * already in a form element; for example, to remove choices which are
  892. * not valid because of additional filters imposed by another module.
  893. * One example might be altering the choices in a taxonomy selector.
  894. * To correctly handle the case of a multiple hierarchy taxonomy,
  895. * #options arrays can now hold an array of objects, instead of a
  896. * direct mapping of keys to labels, so that multiple choices in the
  897. * selector can have the same key (and label). This makes it difficult
  898. * to manipulate directly, which is why this helper function exists.
  899. *
  900. * This function does not support optgroups (when the elements of the
  901. * #options array are themselves arrays), and will return FALSE if
  902. * arrays are found. The caller must either flatten/restore or
  903. * manually do their manipulations in this case, since returning the
  904. * index is not sufficient, and supporting this would make the
  905. * "helper" too complicated and cumbersome to be of any help.
  906. *
  907. * As usual with functions that can return array() or FALSE, do not
  908. * forget to use === and !== if needed.
  909. *
  910. * @param $element
  911. * The select element to search.
  912. * @param $key
  913. * The key to look for.
  914. * @return
  915. * An array of indexes that match the given $key. Array will be
  916. * empty if no elements were found. FALSE if optgroups were found.
  917. */
  918. function form_get_options($element, $key) {
  919. $keys = array();
  920. foreach ($element['#options'] as $index => $choice) {
  921. if (is_array($choice)) {
  922. return FALSE;
  923. }
  924. else if (is_object($choice)) {
  925. if (isset($choice->option[$key])) {
  926. $keys[] = $index;
  927. }
  928. }
  929. else if ($index == $key) {
  930. $keys[] = $index;
  931. }
  932. }
  933. return $keys;
  934. }
  935. /**
  936. * Format a group of form items.
  937. *
  938. * @param $element
  939. * An associative array containing the properties of the element.
  940. * Properties used: attributes, title, value, description, children, collapsible, collapsed
  941. * @return
  942. * A themed HTML string representing the form item group.
  943. */
  944. function theme_fieldset($element) {
  945. if ($element['#collapsible']) {
  946. drupal_add_js('misc/collapse.js');
  947. if (!isset($element['#attributes']['class'])) {
  948. $element['#attributes']['class'] = '';
  949. }
  950. $element['#attributes']['class'] .= ' collapsible';
  951. if ($element['#collapsed']) {
  952. $element['#attributes']['class'] .= ' collapsed';
  953. }
  954. }
  955. return '<fieldset' . drupal_attributes($element['#attributes']) .'>' . ($element['#title'] ? '<legend>'. $element['#title'] .'</legend>' : '') . ($element['#description'] ? '<div class="description">'. $element['#description'] .'</div>' : '') . $element['#children'] . $element['#value'] . "</fieldset>\n";
  956. }
  957. /**
  958. * Format a radio button.
  959. *
  960. * @param $element
  961. * An associative array containing the properties of the element.
  962. * Properties used: required, return_value, value, attributes, title, description
  963. * @return
  964. * A themed HTML string representing the form item group.
  965. */
  966. function theme_radio($element) {
  967. _form_set_class($element, array('form-radio'));
  968. $output = '<input type="radio" ';
  969. $output .= 'name="' . $element['#name'] .'" ';
  970. $output .= 'value="'. $element['#return_value'] .'" ';
  971. $output .= (check_plain($element['#value']) == $element['#return_value']) ? ' checked="checked" ' : ' ';
  972. $output .= drupal_attributes($element['#attributes']) .' />';
  973. if (!is_null($element['#title'])) {
  974. $output = '<label class="option">'. $output .' '. $element['#title'] .'</label>';
  975. }
  976. unset($element['#title']);
  977. return theme('form_element', $element, $output);
  978. }
  979. /**
  980. * Format a set of radio buttons.
  981. *
  982. * @param $element
  983. * An associative array containing the properties of the element.
  984. * Properties used: title, value, options, description, required and attributes.
  985. * @return
  986. * A themed HTML string representing the radio button set.
  987. */
  988. function theme_radios($element) {
  989. $class = 'form-radios';
  990. if (isset($element['#attributes']['class'])) {
  991. $class .= ' '. $element['#attributes']['class'];
  992. }
  993. $element['#children'] = '<div class="'. $class .'">'. $element['#children'] .'</div>';
  994. if ($element['#title'] || $element['#description']) {
  995. unset($element['#id']);
  996. return theme('form_element', $element, $element['#children']);
  997. }
  998. else {
  999. return $element['#children'];
  1000. }
  1001. }
  1002. /**
  1003. * Format a password_confirm item.
  1004. *
  1005. * @param $element
  1006. * An associative array containing the properties of the element.
  1007. * Properties used: title, value, id, required, error.
  1008. * @return
  1009. * A themed HTML string representing the form item.
  1010. */
  1011. function theme_password_confirm($element) {
  1012. return theme('form_element', $element, $element['#children']);
  1013. }
  1014. /**
  1015. * Expand a password_confirm field into two text boxes.
  1016. */
  1017. function expand_password_confirm($element) {
  1018. $element['pass1'] = array(
  1019. '#type' => 'password',
  1020. '#title' => t('Password'),
  1021. '#value' => $element['#value']['pass1'],
  1022. '#required' => $element['#required'],
  1023. );
  1024. $element['pass2'] = array(
  1025. '#type' => 'password',
  1026. '#title' => t('Confirm password'),
  1027. '#value' => $element['#value']['pass2'],
  1028. '#required' => $element['#required'],
  1029. );
  1030. $element['#validate'] = array('password_confirm_validate' => array());
  1031. $element['#tree'] = TRUE;
  1032. if (isset($element['#size'])) {
  1033. $element['pass1']['#size'] = $element['pass2']['#size'] = $element['#size'];
  1034. }
  1035. return $element;
  1036. }
  1037. /**
  1038. * Validate password_confirm element.
  1039. */
  1040. function password_confirm_validate($form) {
  1041. $pass1 = trim($form['pass1']['#value']);
  1042. if (!empty($pass1)) {
  1043. $pass2 = trim($form['pass2']['#value']);
  1044. if ($pass1 != $pass2) {
  1045. form_error($form, t('The specified passwords do not match.'));
  1046. }
  1047. }
  1048. elseif ($form['#required'] && !empty($form['#post'])) {
  1049. form_error($form, t('Password field is required.'));
  1050. }
  1051. // Password field must be converted from a two-element array into a single
  1052. // string regardless of validation results.
  1053. form_set_value($form['pass1'], NULL);
  1054. form_set_value($form['pass2'], NULL);
  1055. form_set_value($form, $pass1);
  1056. return $form;
  1057. }
  1058. /**
  1059. * Format a date selection element.
  1060. *
  1061. * @param $element
  1062. * An associative array containing the properties of the element.
  1063. * Properties used: title, value, options, description, required and attributes.
  1064. * @return
  1065. * A themed HTML string representing the date selection boxes.
  1066. */
  1067. function theme_date($element) {
  1068. return theme('form_element', $element, '<div class="container-inline">'. $element['#children'] .'</div>');
  1069. }
  1070. /**
  1071. * Roll out a single date element.
  1072. */
  1073. function expand_date($element) {
  1074. // Default to current date
  1075. if (empty($element['#value'])) {
  1076. $element['#value'] = array('day' => format_date(time(), 'custom', 'j'),
  1077. 'month' => format_date(time(), 'custom', 'n'),
  1078. 'year' => format_date(time(), 'custom', 'Y'));
  1079. }
  1080. $element['#tree'] = TRUE;
  1081. // Determine the order of day, month, year in the site's chosen date format.
  1082. $format = variable_get('date_format_short', 'm/d/Y - H:i');
  1083. $sort = array();
  1084. $sort['day'] = max(strpos($format, 'd'), strpos($format, 'j'));
  1085. $sort['month'] = max(strpos($format, 'm'), strpos($format, 'M'));
  1086. $sort['year'] = strpos($format, 'Y');
  1087. asort($sort);
  1088. $order = array_keys($sort);
  1089. // Output multi-selector for date.
  1090. foreach ($order as $type) {
  1091. switch ($type) {
  1092. case 'day':
  1093. $options = drupal_map_assoc(range(1, 31));
  1094. break;
  1095. case 'month':
  1096. $options = drupal_map_assoc(range(1, 12), 'map_month');
  1097. break;
  1098. case 'year':
  1099. $options = drupal_map_assoc(range(1900, 2050));
  1100. break;
  1101. }
  1102. $parents = $element['#parents'];
  1103. $parents[] = $type;
  1104. $element[$type] = array(
  1105. '#type' => 'select',
  1106. '#value' => $element['#value'][$type],
  1107. '#attributes' => $element['#attributes'],
  1108. '#options' => $options,
  1109. );
  1110. }
  1111. return $element;
  1112. }
  1113. /**
  1114. * Validates the date type to stop dates like February 30, 2006.
  1115. */
  1116. function date_validate($form) {
  1117. if (!checkdate($form['#value']['month'], $form['#value']['day'], $form['#value']['year'])) {
  1118. form_error($form, t('The specified date is invalid.'));
  1119. }
  1120. }
  1121. /**
  1122. * Helper function for usage with drupal_map_assoc to display month names.
  1123. */
  1124. function map_month($month) {
  1125. return format_date(gmmktime(0, 0, 0, $month, 2, 1970), 'custom', 'M', 0);
  1126. }
  1127. /**
  1128. * Helper function to load value from default value for checkboxes.
  1129. */
  1130. function checkboxes_value(&$form) {
  1131. $value = array();
  1132. foreach ((array)$form['#default_value'] as $key) {
  1133. $value[$key] = 1;
  1134. }
  1135. $form['#value'] = $value;
  1136. }
  1137. /**
  1138. * If no default value is set for weight select boxes, use 0.
  1139. */
  1140. function weight_value(&$form) {
  1141. if (isset($form['#default_value'])) {
  1142. $form['#value'] = $form['#default_value'];
  1143. }
  1144. else {
  1145. $form['#value'] = 0;
  1146. }
  1147. }
  1148. /**
  1149. * Roll out a single radios element to a list of radios,
  1150. * using the options array as index.
  1151. */
  1152. function expand_radios($element) {
  1153. if (count($element['#options']) > 0) {
  1154. foreach ($element['#options'] as $key => $choice) {
  1155. if (!isset($element[$key])) {
  1156. // Generate the parents as the autogenerator does, so we will have a
  1157. // unique id for each radio button.
  1158. $parents_for_id = array_merge($element['#parents'], array($key));
  1159. $element[$key] = array(
  1160. '#type' => 'radio',
  1161. '#title' => $choice,
  1162. '#return_value' => check_plain($key),
  1163. '#default_value' => $element['#default_value'],
  1164. '#attributes' => $element['#attributes'],
  1165. '#id' => form_clean_id('edit-'. implode('-', $parents_for_id)),
  1166. '#parents' => $element['#parents'],
  1167. '#spawned' => TRUE
  1168. );
  1169. }
  1170. }
  1171. }
  1172. return $element;
  1173. }
  1174. /**
  1175. * Format a form item.
  1176. *
  1177. * @param $element
  1178. * An associative array containing the properties of the element.
  1179. * Properties used: title, value, description, required, error
  1180. * @return
  1181. * A themed HTML string representing the form item.
  1182. */
  1183. function theme_item($element) {
  1184. return theme('form_element', $element, $element['#value'] . $element['#children']);
  1185. }
  1186. /**
  1187. * Format a checkbox.
  1188. *
  1189. * @param $element
  1190. * An associative array containing the properties of the element.
  1191. * Properties used: title, value, return_value, description, required
  1192. * @return
  1193. * A themed HTML string representing the checkbox.
  1194. */
  1195. function theme_checkbox($element) {
  1196. _form_set_class($element, array('form-checkbox'));
  1197. $checkbox = '<input ';
  1198. $checkbox .= 'type="checkbox" ';
  1199. $checkbox .= 'name="'. $element['#name'] .'" ';
  1200. $checkbox .= 'id="'. $element['#id'].'" ' ;
  1201. $checkbox .= 'value="'. $element['#return_value'] .'" ';
  1202. $checkbox .= $element['#value'] ? ' checked="checked" ' : ' ';
  1203. $checkbox .= drupal_attributes($element['#attributes']) . ' />';
  1204. if (!is_null($element['#title'])) {
  1205. $checkbox = '<label class="option">'. $checkbox .' '. $element['#title'] .'</label>';
  1206. }
  1207. unset($element['#title']);
  1208. return theme('form_element', $element, $checkbox);
  1209. }
  1210. /**
  1211. * Format a set of checkboxes.
  1212. *
  1213. * @param $element
  1214. * An associative array containing the properties of the element.
  1215. * @return
  1216. * A themed HTML string representing the checkbox set.
  1217. */
  1218. function theme_checkboxes($element) {
  1219. $class = 'form-checkboxes';
  1220. if (isset($element['#attributes']['class'])) {
  1221. $class .= ' '. $element['#attributes']['class'];
  1222. }
  1223. $element['#children'] = '<div class="'. $class .'">'. $element['#children'] .'</div>';
  1224. if ($element['#title'] || $element['#description']) {
  1225. unset($element['#id']);
  1226. return theme('form_element', $element, $element['#children']);
  1227. }
  1228. else {
  1229. return $element['#children'];
  1230. }
  1231. }
  1232. function expand_checkboxes($element) {
  1233. $value = is_array($element['#value']) ? $element['#value'] : array();
  1234. $element['#tree'] = TRUE;
  1235. if (count($element['#options']) > 0) {
  1236. if (!isset($element['#default_value']) || $element['#default_value'] == 0) {
  1237. $element['#default_value'] = array();
  1238. }
  1239. foreach ($element['#options'] as $key => $choice) {
  1240. if (!isset($element[$key])) {
  1241. $element[$key] = array('#type' => 'checkbox', '#processed' => TRUE, '#title' => $choice, '#return_value' => $key, '#default_value' => isset($value[$key]), '#attributes' => $element['#attributes']);
  1242. }
  1243. }
  1244. }
  1245. return $element;
  1246. }
  1247. function theme_submit($element) {
  1248. return theme('button', $element);
  1249. }
  1250. function theme_button($element) {
  1251. // Make sure not to overwrite classes.
  1252. if (isset($element['#attributes']['class'])) {
  1253. $element['#attributes']['class'] = 'form-'. $element['#button_type'] .' '. $element['#attributes']['class'];
  1254. }
  1255. else {
  1256. $element['#attributes']['class'] = 'form-'. $element['#button_type'];
  1257. }
  1258. return '<input type="submit" '. (empty($element['#name']) ? '' : 'name="'. $element['#name'] .'" ') .'id="'. $element['#id'].'" value="'. check_plain($element['#value']) .'" '. drupal_attributes($element['#attributes']) ." />\n";
  1259. }
  1260. /**
  1261. * Format a hidden form field.
  1262. *
  1263. * @param $element
  1264. * An associative array containing the properties of the element.
  1265. * Properties used: value, edit
  1266. * @return
  1267. * A themed HTML string representing the hidden form field.
  1268. */
  1269. function theme_hidden($element) {
  1270. return '<input type="hidden" name="'. $element['#name'] . '" id="'. $element['#id'] . '" value="'. check_plain($element['#value']) ."\" " . drupal_attributes($element['#attributes']) ." />\n";
  1271. }
  1272. function theme_token($element) {
  1273. return theme('hidden', $element);
  1274. }
  1275. /**
  1276. * Format a textfield.
  1277. *
  1278. * @param $element
  1279. * An associative array containing the properties of the element.
  1280. * Properties used: title, value, description, size, maxlength, required, attributes autocomplete_path
  1281. * @return
  1282. * A themed HTML string representing the textfield.
  1283. */
  1284. function theme_textfield($element) {
  1285. $size = $element['#size'] ? ' size="' . $element['#size'] . '"' : '';
  1286. $class = array('form-text');
  1287. $extra = '';
  1288. $output = '';
  1289. if ($element['#autocomplete_path']) {
  1290. drupal_add_js('misc/autocomplete.js');
  1291. $class[] = 'form-autocomplete';
  1292. $extra = '<input class="autocomplete" type="hidden" id="'. $element['#id'] .'-autocomplete" value="'. check_url(url($element['#autocomplete_path'], NULL, NULL, TRUE)) .'" disabled="disabled" />';
  1293. }
  1294. _form_set_class($element, $class);
  1295. if (isset($element['#field_prefix'])) {
  1296. $output .= '<span class="field-prefix">'. $element['#field_prefix'] .'</span> ';
  1297. }
  1298. $output .= '<input type="text" maxlength="'. $element['#maxlength'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. $size .' value="'. check_plain($element['#value']) .'"'. drupal_attributes($element['#attributes']) .' />';
  1299. if (isset($element['#field_suffix'])) {
  1300. $output .= ' <span class="field-suffix">'. $element['#field_suffix'] .'</span>';
  1301. }
  1302. return theme('form_element', $element, $output). $extra;
  1303. }
  1304. /**
  1305. * Format a form.
  1306. *
  1307. * @param $element
  1308. * An associative array containing the properties of the element.
  1309. * Properties used: action, method, attributes, children
  1310. * @return
  1311. * A themed HTML string representing the form.
  1312. */
  1313. function theme_form($element) {
  1314. // Anonymous div to satisfy XHTML compliance.
  1315. $action = $element['#action'] ? 'action="' . check_url($element['#action']) . '" ' : '';
  1316. return '<form '. $action .' accept-charset="UTF-8" method="'. $element['#method'] .'" '. 'id="'. $element['#id'] .'"'. drupal_attributes($element['#attributes']) .">\n<div>". $element['#children'] ."\n</div></form>\n";
  1317. }
  1318. /**
  1319. * Format a textarea.
  1320. *
  1321. * @param $element
  1322. * An associative array containing the properties of the element.
  1323. * Properties used: title, value, description, rows, cols, required, attributes
  1324. * @return
  1325. * A themed HTML string representing the textarea.
  1326. */
  1327. function theme_textarea($element) {
  1328. $class = array('form-textarea');
  1329. if ($element['#resizable'] !== FALSE) {
  1330. drupal_add_js('misc/textarea.js');
  1331. $class[] = 'resizable';
  1332. }
  1333. $cols = $element['#cols'] ? ' cols="'. $element['#cols'] .'"' : '';
  1334. _form_set_class($element, $class);
  1335. return theme('form_element', $element, '<textarea'. $cols .' rows="'. $element['#rows'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. drupal_attributes($element['#attributes']) .'>'. check_plain($element['#value']) .'</textarea>');
  1336. }
  1337. /**
  1338. * Format HTML markup for use in forms.
  1339. *
  1340. * This is used in more advanced forms, such as theme selection and filter format.
  1341. *
  1342. * @param $element
  1343. * An associative array containing the properties of the element.
  1344. * Properties used: value, children.
  1345. * @return
  1346. * A themed HTML string representing the HTML markup.
  1347. */
  1348. function theme_markup($element) {
  1349. return (isset($element['#value']) ? $element['#value'] : '') . (isset($element['#children']) ? $element['#children'] : '');
  1350. }
  1351. /**
  1352. * Format a password field.
  1353. *
  1354. * @param $element
  1355. * An associative array containing the properties of the element.
  1356. * Properties used: title, value, description, size, maxlength, required, attributes
  1357. * @return
  1358. * A themed HTML string representing the form.
  1359. */
  1360. function theme_password($element) {
  1361. $size = $element['#size'] ? ' size="'. $element['#size'] .'" ' : '';
  1362. $maxlength = $element['#maxlength'] ? ' maxlength="'. $element['#maxlength'] .'" ' : '';
  1363. _form_set_class($element, array('form-text'));
  1364. $output = '<input type="password" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. $maxlength . $size . drupal_attributes($element['#attributes']) .' />';
  1365. return theme('form_element', $element, $output);
  1366. }
  1367. /**
  1368. * Expand weight elements into selects.
  1369. */
  1370. function process_weight($element) {
  1371. for ($n = (-1 * $element['#delta']); $n <= $element['#delta']; $n++) {
  1372. $weights[$n] = $n;
  1373. }
  1374. $element['#options'] = $weights;
  1375. $element['#type'] = 'select';
  1376. $element['#is_weight'] = TRUE;
  1377. return $element;
  1378. }
  1379. /**
  1380. * Format a file upload field.
  1381. *
  1382. * @param $title
  1383. * The label for the file upload field.
  1384. * @param $name
  1385. * The internal name used to refer to the field.
  1386. * @param $size
  1387. * A measure of the visible size of the field (passed directly to HTML).
  1388. * @param $description
  1389. * Explanatory text to display after the form item.
  1390. * @param $required
  1391. * Whether the user must upload a file to the field.
  1392. * @return
  1393. * A themed HTML string representing the field.
  1394. *
  1395. * For assistance with handling the uploaded file correctly, see the API
  1396. * provided by file.inc.
  1397. */
  1398. function theme_file($element) {
  1399. _form_set_class($element, array('form-file'));
  1400. return theme('form_element', $element, '<input type="file" name="'. $element['#name'] .'"'. ($element['#attributes'] ? ' '. drupal_attributes($element['#attributes']) : '') .' id="'. $element['#id'] .'" size="'. $element['#size'] ."\" />\n");
  1401. }
  1402. /**
  1403. * Return a themed form element.
  1404. *
  1405. * @param element
  1406. * An associative array containing the properties of the element.
  1407. * Properties used: title, description, id, required
  1408. * @param $value
  1409. * The form element's data.
  1410. * @return
  1411. * A string representing the form element.
  1412. */
  1413. function theme_form_element($element, $value) {
  1414. $output = '<div class="form-item"';
  1415. if (!empty($element['#id'])) {
  1416. $output .= ' id="'. $element['#id'] .'-wrapper"';
  1417. }
  1418. $output .= ">\n";
  1419. $required = !empty($element['#required']) ? '<span class="form-required" title="'. t('This field is required.') .'">*</span>' : '';
  1420. if (!empty($element['#title'])) {
  1421. $title = $element['#title'];
  1422. if (!empty($element['#id'])) {
  1423. $output .= ' <label for="'. $element['#id'] .'">'. t('!title: !required', array('!title' => filter_xss_admin($title), '!required' => $required)) ."</label>\n";
  1424. }
  1425. else {
  1426. $output .= ' <label>'. t('!title: !required', array('!title' => filter_xss_admin($title), '!required' => $required)) ."</label>\n";
  1427. }
  1428. }
  1429. $output .= " $value\n";
  1430. if (!empty($element['#description'])) {
  1431. $output .= ' <div class="description">'. $element['#description'] ."</div>\n";
  1432. }
  1433. $output .= "</div>\n";
  1434. return $output;
  1435. }
  1436. /**
  1437. * Sets a form element's class attribute.
  1438. *
  1439. * Adds 'required' and 'error' classes as needed.
  1440. *
  1441. * @param &$element
  1442. * The form element.
  1443. * @param $name
  1444. * Array of new class names to be added.
  1445. */
  1446. function _form_set_class(&$element, $class = array()) {
  1447. if ($element['#required']) {
  1448. $class[] = 'required';
  1449. }
  1450. if (form_get_error($element)){
  1451. $class[] = 'error';
  1452. }
  1453. if (isset($element['#attributes']['class'])) {
  1454. $class[] = $element['#attributes']['class'];
  1455. }
  1456. $element['#attributes']['class'] = implode(' ', $class);
  1457. }
  1458. /**
  1459. * Remove invalid characters from an HTML ID attribute string.
  1460. *
  1461. * @param $id
  1462. * The ID to clean.
  1463. * @return
  1464. * The cleaned ID.
  1465. */
  1466. function form_clean_id($id = NULL) {
  1467. $id = str_replace(array('][', '_', ' '), '-', $id);
  1468. return $id;
  1469. }
  1470. /**
  1471. * @} End of "defgroup form".
  1472. */

Functions

Namesort descending Description
checkboxes_value Helper function to load value from default value for checkboxes.
date_validate Validates the date type to stop dates like February 30, 2006.
drupal_execute Retrieves a form using a form_id, populates it with $form_values, processes it, and returns any validation errors encountered. This function is the programmatic counterpart to drupal_get_form().
drupal_get_form Retrieves a form from a builder function, passes it on for processing, and renders the form or redirects to its destination as appropriate. In multi-step form scenarios, it handles properly processing the values using the previous step's form…
drupal_prepare_form Prepares a structured form array by adding required elements, executing any hook_form_alter functions, and optionally inserting a validation token to prevent tampering.
drupal_process_form This function is the heart of form API. The form gets built, validated and in appropriate cases, submitted.
drupal_redirect_form Redirect the user to a URL after a form has been processed.
drupal_render_form Renders a structured form array into themed HTML.
drupal_retrieve_form Retrieves the structured array that defines a given form.
drupal_submit_form Processes user-submitted form data from a global variable using the submit functions defined in a structured form array.
drupal_validate_form Validates user-submitted form data from a global variable using the validate functions defined in a structured form array.
expand_checkboxes
expand_date Roll out a single date element.
expand_password_confirm Expand a password_confirm field into two text boxes.
expand_radios Roll out a single radios element to a list of radios, using the options array as index.
form_builder Adds some required properties to each form element, which are used internally in the form API. This function also automatically assigns the value property from the $edit array, provided the element doesn't already have an assigned value.
form_clean_id Remove invalid characters from an HTML ID attribute string.
form_error Flag an element as having an error.
form_get_error Return the error message filed against the form with the specified name.
form_get_errors Return an associative array of all errors.
form_get_options Traverses a select element's #option array looking for any values that hold the given key. Returns an array of indexes that match.
form_options_flatten
form_select_options
form_set_error File an error against a form element. If the name of the element is edit[foo][bar] then you may pass either foo or foo][bar as $name foo will set an error for all its children.
form_set_value Use this function to make changes to form values in the form validate phase, so they will be available in the submit phase in $form_values.
map_month Helper function for usage with drupal_map_assoc to display month names.
password_confirm_validate Validate password_confirm element.
process_weight Expand weight elements into selects.
theme_button
theme_checkbox Format a checkbox.
theme_checkboxes Format a set of checkboxes.
theme_date Format a date selection element.
theme_fieldset Format a group of form items.
theme_file Format a file upload field.
theme_form Format a form.
theme_form_element Return a themed form element.
theme_hidden Format a hidden form field.
theme_item Format a form item.
theme_markup
theme_password Format a password field. *
theme_password_confirm Format a password_confirm item.
theme_radio Format a radio button.
theme_radios Format a set of radio buttons.
theme_select Format a dropdown menu or scrolling selection box.
theme_submit
theme_textarea Format a textarea.
theme_textfield Format a textfield.
theme_token
weight_value If no default value is set for weight select boxes, use 0.
_drupal_clean_form_sessions Remove form information that's at least a day old from the $_SESSION['form'] array.
_element_info Retrieve the default properties for the defined element type.
_form_set_class Sets a form element's class attribute.
_form_set_value Helper function for form_set_value().
_form_validate Performs validation on form elements. First ensures required fields are completed, #maxlength is not exceeded, and selected options were in the list of options given to the user. Then calls user-defined validators.