wizard.inc 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534
  1. <?php
  2. /**
  3. * @file
  4. * CTools' multi-step form wizard tool.
  5. *
  6. * This tool enables the creation of multi-step forms that go from one
  7. * form to another. The forms themselves can allow branching if they
  8. * like, and there are a number of configurable options to how
  9. * the wizard operates.
  10. *
  11. * The wizard can also be friendly to ajax forms, such as when used
  12. * with the modal tool.
  13. *
  14. * The wizard provides callbacks throughout the process, allowing the
  15. * owner to control the flow. The general flow of what happens is:
  16. *
  17. * Generate a form
  18. * submit a form
  19. * based upon button clicked, 'finished', 'next form', 'cancel' or 'return'.
  20. *
  21. * Each action has its own callback, so cached objects can be modifed and or
  22. * turned into real objects. Each callback can make decisions about where to
  23. * go next if it wishes to override the default flow.
  24. */
  25. /**
  26. * Display a multi-step form.
  27. *
  28. * Aside from the addition of the $form_info which contains an array of
  29. * information and configuration so the multi-step wizard can do its thing,
  30. * this function works a lot like drupal_build_form.
  31. *
  32. * Remember that the form builders for this form will receive
  33. * &$form, &$form_state, NOT just &$form_state and no additional args.
  34. *
  35. * @param $form_info
  36. * An array of form info. @todo document the array.
  37. * @param $step
  38. * The current form step.
  39. * @param &$form_state
  40. * The form state array; this is a reference so the caller can get back
  41. * whatever information the form(s) involved left for it.
  42. */
  43. function ctools_wizard_multistep_form($form_info, $step, &$form_state) {
  44. // Make sure 'wizard' always exists for the form when dealing
  45. // with form caching.
  46. ctools_form_include($form_state, 'wizard');
  47. // allow order array to be optional
  48. if (empty($form_info['order'])) {
  49. foreach ($form_info['forms'] as $step_id => $params) {
  50. $form_info['order'][$step_id] = $params['title'];
  51. }
  52. }
  53. if (!isset($step)) {
  54. $keys = array_keys($form_info['order']);
  55. $step = array_shift($keys);
  56. }
  57. ctools_wizard_defaults($form_info);
  58. // If automated caching is enabled, ensure that everything is as it
  59. // should be.
  60. if (!empty($form_info['auto cache'])) {
  61. // If the cache mechanism hasn't been set, default to the simple
  62. // mechanism and use the wizard ID to ensure uniqueness so cache
  63. // objects don't stomp on each other.
  64. if (!isset($form_info['cache mechanism'])) {
  65. $form_info['cache mechanism'] = 'simple::wizard::' . $form_info['id'];
  66. }
  67. // If not set, default the cache key to the wizard ID. This is often
  68. // a unique ID of the object being edited or similar.
  69. if (!isset($form_info['cache key'])) {
  70. $form_info['cache key'] = $form_info['id'];
  71. }
  72. // If not set, default the cache location to storage. This is often
  73. // somnething like 'conf'.
  74. if (!isset($form_info['cache location'])) {
  75. $form_info['cache location'] = 'storage';
  76. }
  77. // If absolutely nothing was set for the cache area to work on
  78. if (!isset($form_state[$form_info['cache location']])) {
  79. ctools_include('cache');
  80. $form_state[$form_info['cache location']] = ctools_cache_get($form_info['cache mechanism'], $form_info['cache key']);
  81. }
  82. }
  83. $form_state['step'] = $step;
  84. $form_state['form_info'] = $form_info;
  85. // Ensure we have form information for the current step.
  86. if (!isset($form_info['forms'][$step])) {
  87. return;
  88. }
  89. // Ensure that whatever include file(s) were requested by the form info are
  90. // actually included.
  91. $info = $form_info['forms'][$step];
  92. if (!empty($info['include'])) {
  93. if (is_array($info['include'])) {
  94. foreach ($info['include'] as $file) {
  95. ctools_form_include_file($form_state, $file);
  96. }
  97. }
  98. else {
  99. ctools_form_include_file($form_state, $info['include']);
  100. }
  101. }
  102. // This tells drupal_build_form to apply our wrapper to the form. It
  103. // will give it buttons and the like.
  104. $form_state['wrapper_callback'] = 'ctools_wizard_wrapper';
  105. if (!isset($form_state['rerender'])) {
  106. $form_state['rerender'] = FALSE;
  107. }
  108. $form_state['no_redirect'] = TRUE;
  109. $output = drupal_build_form($info['form id'], $form_state);
  110. if (empty($form_state['executed']) || !empty($form_state['rerender'])) {
  111. if (empty($form_state['title']) && !empty($info['title'])) {
  112. $form_state['title'] = $info['title'];
  113. }
  114. if (!empty($form_state['ajax render'])) {
  115. // Any include files should already be included by this point:
  116. return $form_state['ajax render']($form_state, $output);
  117. }
  118. // Automatically use the modal tool if set to true.
  119. if (!empty($form_state['modal']) && empty($form_state['modal return'])) {
  120. ctools_include('modal');
  121. // This overwrites any previous commands.
  122. $form_state['commands'] = ctools_modal_form_render($form_state, $output);
  123. }
  124. }
  125. if (!empty($form_state['executed'])) {
  126. // We use the plugins get_function format because it's powerful and
  127. // not limited to just functions.
  128. ctools_include('plugins');
  129. if (isset($form_state['clicked_button']['#wizard type'])) {
  130. $type = $form_state['clicked_button']['#wizard type'];
  131. // If we have a callback depending upon the type of button that was
  132. // clicked, call it.
  133. if ($function = ctools_plugin_get_function($form_info, "$type callback")) {
  134. $function($form_state);
  135. }
  136. // If auto-caching is on, we need to write the cache on next and
  137. // clear the cache on finish.
  138. if (!empty($form_info['auto cache'])) {
  139. if ($type == 'next') {
  140. ctools_include('cache');
  141. ctools_cache_set($form_info['cache mechanism'], $form_info['cache key'], $form_state[$form_info['cache location']]);
  142. }
  143. elseif ($type == 'finish') {
  144. ctools_include('cache');
  145. ctools_cache_clear($form_info['cache mechanism'], $form_info['cache key']);
  146. }
  147. }
  148. // Set a couple of niceties:
  149. if ($type == 'finish') {
  150. $form_state['complete'] = TRUE;
  151. }
  152. if ($type == 'cancel') {
  153. $form_state['cancel'] = TRUE;
  154. }
  155. // If the modal is in use, some special code for it:
  156. if (!empty($form_state['modal']) && empty($form_state['modal return'])) {
  157. if ($type != 'next') {
  158. // Automatically dismiss the modal if we're not going to another form.
  159. ctools_include('modal');
  160. $form_state['commands'][] = ctools_modal_command_dismiss();
  161. }
  162. }
  163. }
  164. if (empty($form_state['ajax'])) {
  165. // redirect, if one is set.
  166. if ($form_state['redirect']) {
  167. if (is_array($form_state['redirect'])) {
  168. call_user_func_array('drupal_goto', $form_state['redirect']);
  169. }
  170. else {
  171. drupal_goto($form_state['redirect']);
  172. }
  173. }
  174. }
  175. else if (isset($form_state['ajax next'])) {
  176. // Clear a few items off the form state so we don't double post:
  177. $next = $form_state['ajax next'];
  178. unset($form_state['ajax next']);
  179. unset($form_state['executed']);
  180. unset($form_state['post']);
  181. unset($form_state['next']);
  182. return ctools_wizard_multistep_form($form_info, $next, $form_state);
  183. }
  184. // If the callbacks wanted to do something besides go to the next form,
  185. // it needs to have set $form_state['commands'] with something that can
  186. // be rendered.
  187. }
  188. // Render ajax commands if we have any.
  189. if (isset($form_state['ajax']) && isset($form_state['commands']) && empty($form_state['modal return'])) {
  190. return ajax_render($form_state['commands']);
  191. }
  192. // Otherwise, return the output.
  193. return $output;
  194. }
  195. /**
  196. * Provide a wrapper around another form for adding multi-step information.
  197. */
  198. function ctools_wizard_wrapper($form, &$form_state) {
  199. $form_info = &$form_state['form_info'];
  200. $info = $form_info['forms'][$form_state['step']];
  201. // Determine the next form from this step.
  202. // Create a form trail if we're supposed to have one.
  203. $trail = array();
  204. $previous = TRUE;
  205. foreach ($form_info['order'] as $id => $title) {
  206. if ($id == $form_state['step']) {
  207. $previous = FALSE;
  208. $class = 'wizard-trail-current';
  209. }
  210. elseif ($previous) {
  211. $not_first = TRUE;
  212. $class = 'wizard-trail-previous';
  213. $form_state['previous'] = $id;
  214. }
  215. else {
  216. $class = 'wizard-trail-next';
  217. if (!isset($form_state['next'])) {
  218. $form_state['next'] = $id;
  219. }
  220. if (empty($form_info['show trail'])) {
  221. break;
  222. }
  223. }
  224. if (!empty($form_info['show trail'])) {
  225. if (!empty($form_info['free trail'])) {
  226. // ctools_wizard_get_path() returns results suitable for
  227. // $form_state['redirect] which can only be directly used in
  228. // drupal_goto. We have to futz a bit with it.
  229. $path = ctools_wizard_get_path($form_info, $id);
  230. $options = array();
  231. if (!empty($path[1])) {
  232. $options = $path[1];
  233. }
  234. $title = l($title, $path[0], $options);
  235. }
  236. $trail[] = '<span class="' . $class . '">' . $title . '</span>';
  237. }
  238. }
  239. // Display the trail if instructed to do so.
  240. if (!empty($form_info['show trail'])) {
  241. ctools_add_css('wizard');
  242. $form['ctools_trail'] = array(
  243. '#markup' => theme(array('ctools_wizard_trail__' . $form_info['id'], 'ctools_wizard_trail'), array('trail' => $trail, 'form_info' => $form_info)),
  244. '#weight' => -1000,
  245. );
  246. }
  247. if (empty($form_info['no buttons'])) {
  248. // Ensure buttons stay on the bottom.
  249. $form['buttons'] = array(
  250. '#type' => 'actions',
  251. '#weight' => 1000,
  252. );
  253. $button_attributes = array();
  254. if (!empty($form_state['ajax']) && empty($form_state['modal'])) {
  255. $button_attributes = array('class' => array('ctools-use-ajax'));
  256. }
  257. if (!empty($form_info['show back']) && isset($form_state['previous'])) {
  258. $form['buttons']['previous'] = array(
  259. '#type' => 'submit',
  260. '#value' => $form_info['back text'],
  261. '#next' => $form_state['previous'],
  262. '#wizard type' => 'next',
  263. '#weight' => -2000,
  264. '#limit_validation_errors' => array(),
  265. // hardcode the submit so that it doesn't try to save data.
  266. '#submit' => array('ctools_wizard_submit'),
  267. '#attributes' => $button_attributes,
  268. );
  269. if (isset($form_info['no back validate']) || isset($info['no back validate'])) {
  270. $form['buttons']['previous']['#validate'] = array();
  271. }
  272. }
  273. // If there is a next form, place the next button.
  274. if (isset($form_state['next']) || !empty($form_info['free trail'])) {
  275. $form['buttons']['next'] = array(
  276. '#type' => 'submit',
  277. '#value' => $form_info['next text'],
  278. '#next' => !empty($form_info['free trail']) ? $form_state['step'] : $form_state['next'],
  279. '#wizard type' => 'next',
  280. '#weight' => -1000,
  281. '#attributes' => $button_attributes,
  282. );
  283. }
  284. // There are two ways the return button can appear. If this is not the
  285. // end of the form list (i.e, there is a next) then it's "update and return"
  286. // to be clear. If this is the end of the path and there is no next, we
  287. // call it 'Finish'.
  288. // Even if there is no direct return path (some forms may not want you
  289. // leaving in the middle) the final button is always a Finish and it does
  290. // whatever the return action is.
  291. if (!empty($form_info['show return']) && !empty($form_state['next'])) {
  292. $form['buttons']['return'] = array(
  293. '#type' => 'submit',
  294. '#value' => $form_info['return text'],
  295. '#wizard type' => 'return',
  296. '#attributes' => $button_attributes,
  297. );
  298. }
  299. else if (empty($form_state['next']) || !empty($form_info['free trail'])) {
  300. $form['buttons']['return'] = array(
  301. '#type' => 'submit',
  302. '#value' => $form_info['finish text'],
  303. '#wizard type' => 'finish',
  304. '#attributes' => $button_attributes,
  305. );
  306. }
  307. // If we are allowed to cancel, place a cancel button.
  308. if ((isset($form_info['cancel path']) && !isset($form_info['show cancel'])) || !empty($form_info['show cancel'])) {
  309. $form['buttons']['cancel'] = array(
  310. '#type' => 'submit',
  311. '#value' => $form_info['cancel text'],
  312. '#wizard type' => 'cancel',
  313. // hardcode the submit so that it doesn't try to save data.
  314. '#limit_validation_errors' => array(),
  315. '#submit' => array('ctools_wizard_submit'),
  316. '#attributes' => $button_attributes,
  317. );
  318. }
  319. // Set up optional validate handlers.
  320. $form['#validate'] = array();
  321. if (function_exists($info['form id'] . '_validate')) {
  322. $form['#validate'][] = $info['form id'] . '_validate';
  323. }
  324. if (isset($info['validate']) && function_exists($info['validate'])) {
  325. $form['#validate'][] = $info['validate'];
  326. }
  327. // Set up our submit handler after theirs. Since putting something here will
  328. // skip Drupal's autodetect, we autodetect for it.
  329. // We make sure ours is after theirs so that they get to change #next if
  330. // the want to.
  331. $form['#submit'] = array();
  332. if (function_exists($info['form id'] . '_submit')) {
  333. $form['#submit'][] = $info['form id'] . '_submit';
  334. }
  335. if (isset($info['submit']) && function_exists($info['submit'])) {
  336. $form['#submit'][] = $info['submit'];
  337. }
  338. $form['#submit'][] = 'ctools_wizard_submit';
  339. }
  340. if (!empty($form_state['ajax'])) {
  341. $params = ctools_wizard_get_path($form_state['form_info'], $form_state['step']);
  342. if (count($params) > 1) {
  343. $url = array_shift($params);
  344. $options = array();
  345. $keys = array(0 => 'query', 1 => 'fragment');
  346. foreach ($params as $key => $value) {
  347. if (isset($keys[$key]) && isset($value)) {
  348. $options[$keys[$key]] = $value;
  349. }
  350. }
  351. $params = array($url, $options);
  352. }
  353. $form['#action'] = call_user_func_array('url', $params);
  354. }
  355. if (isset($info['wrapper']) && function_exists($info['wrapper'])) {
  356. $form = $info['wrapper']($form, $form_state);
  357. }
  358. if (isset($form_info['wrapper']) && function_exists($form_info['wrapper'])) {
  359. $form = $form_info['wrapper']($form, $form_state);
  360. }
  361. return $form;
  362. }
  363. /**
  364. * On a submit, go to the next form.
  365. */
  366. function ctools_wizard_submit(&$form, &$form_state) {
  367. if (isset($form_state['clicked_button']['#wizard type'])) {
  368. $type = $form_state['clicked_button']['#wizard type'];
  369. // if AJAX enabled, we proceed slightly differently here.
  370. if (!empty($form_state['ajax'])) {
  371. if ($type == 'next') {
  372. $form_state['ajax next'] = $form_state['clicked_button']['#next'];
  373. }
  374. }
  375. else {
  376. if ($type == 'cancel' && isset($form_state['form_info']['cancel path'])) {
  377. $form_state['redirect'] = $form_state['form_info']['cancel path'];
  378. }
  379. else if ($type == 'next') {
  380. $form_state['redirect'] = ctools_wizard_get_path($form_state['form_info'], $form_state['clicked_button']['#next']);
  381. if (!empty($_GET['destination'])) {
  382. // We don't want drupal_goto redirect this request
  383. // back. ctools_wizard_get_path ensures that the destination is
  384. // carried over on subsequent pages.
  385. unset($_GET['destination']);
  386. }
  387. }
  388. else if (isset($form_state['form_info']['return path'])) {
  389. $form_state['redirect'] = $form_state['form_info']['return path'];
  390. }
  391. else if ($type == 'finish' && isset($form_state['form_info']['cancel path'])) {
  392. $form_state['redirect'] = $form_state['form_info']['cancel path'];
  393. }
  394. }
  395. }
  396. }
  397. /**
  398. * Create a path from the form info and a given step.
  399. */
  400. function ctools_wizard_get_path($form_info, $step) {
  401. if (is_array($form_info['path'])) {
  402. foreach ($form_info['path'] as $id => $part) {
  403. $form_info['path'][$id] = str_replace('%step', $step, $form_info['path'][$id]);
  404. }
  405. $path = $form_info['path'];
  406. }
  407. else {
  408. $path = array(str_replace('%step', $step, $form_info['path']));
  409. }
  410. // If destination is set, carry it over so it'll take effect when
  411. // saving. The submit handler will unset destination to avoid drupal_goto
  412. // redirecting us.
  413. if (!empty($_GET['destination'])) {
  414. // Ensure that options is an array.
  415. if (!isset($path[1]) || !is_array($path[1])) {
  416. $path[1] = array();
  417. }
  418. // Ensure that the query part of options is an array.
  419. $path[1] += array('query' => array());
  420. // Add the destination parameter, if not set already.
  421. $path[1]['query'] += drupal_get_destination();
  422. }
  423. return $path;
  424. }
  425. /**
  426. * Set default parameters and callbacks if none are given.
  427. * Callbacks follows pattern:
  428. * $form_info['id']_$hook
  429. * $form_info['id']_$form_info['forms'][$step_key]_$hook
  430. */
  431. function ctools_wizard_defaults(&$form_info) {
  432. $hook = $form_info['id'];
  433. $defaults = array(
  434. 'show trail' => FALSE,
  435. 'free trail' => FALSE,
  436. 'show back' => FALSE,
  437. 'show cancel' => FALSE,
  438. 'show return' => FALSE,
  439. 'next text' => t('Continue'),
  440. 'back text' => t('Back'),
  441. 'return text' => t('Update and return'),
  442. 'finish text' => t('Finish'),
  443. 'cancel text' => t('Cancel'),
  444. );
  445. if (!empty($form_info['free trail'])) {
  446. $defaults['next text'] = t('Update');
  447. $defaults['finish text'] = t('Save');
  448. }
  449. $form_info = $form_info + $defaults;
  450. // set form callbacks if they aren't defined
  451. foreach ($form_info['forms'] as $step => $params) {
  452. if (!$params['form id']) {
  453. $form_callback = $hook . '_' . $step . '_form';
  454. $form_info['forms'][$step]['form id'] = $form_callback;
  455. }
  456. }
  457. // set button callbacks
  458. $callbacks = array(
  459. 'back callback' => '_back',
  460. 'next callback' => '_next',
  461. 'return callback' => '_return',
  462. 'cancel callback' => '_cancel',
  463. 'finish callback' => '_finish',
  464. );
  465. foreach ($callbacks as $key => $callback) {
  466. // never overwrite if explicity defined
  467. if (empty($form_info[$key])) {
  468. $wizard_callback = $hook . $callback;
  469. if (function_exists($wizard_callback)) {
  470. $form_info[$key] = $wizard_callback;
  471. }
  472. }
  473. }
  474. }