Chaos tool suite's

Form wizard tool

Who am I?

oadaeh

d.o UID: 4649 (10 years 1 month)

Mass Contact, Basic webmail

Live in: Las Vegas, NV

Organizer of the

Drupal User Group of Las Vegas:

http://dug.lv/

Ask away – don't wait until the end

Audience survey

Who has ever attempted to use the Form wizard tool?

Who has ever attempted multi-step forms in Drupal using another method?

What are the other methods you have used?

Other Examples

What it is

What is the Form wizard tool?

It is a way to make multi-step forms less difficult

What are multi-step forms?

A series of forms culminating in a single or group of actions

What it is not

What the Form wizard tool is not

A point-and-click GUI interface to set up a multi-step forms wizard

How Drupal does it

Drupal's FAPI wants to own the process

Form callback builds entire form

Submit callback saves entire form

Standard multistep means having entire form, only showing part of it, doing weird things in submit

Drupal's FAPI

FormPage callback

Render

Save

drupal_goto()

You must unlearnwhat you have learned

You cannot be successful with multi-step forms, unless you divorce the form presentation from the data

Your form doesn't load, save, or own your data

Your form is a view in the MVC sense; it is a view of the data only

Paradigm Shift

WizardPage callback

Render

Save

drupal_goto()

Form

Form

FormForm

Broad overview(the parts of the wizard)

Entry point into main function (hook_menu())

The main function, which defines and initiates the wizard

The data, which is an object

Object caching

Form functions

Callbacks – the wizard interacting functions

Start at the beginning

Install and enable:

Chaos tools suite

Only the main Ctools module needs to be enabled

Advanced Help

Only if you want the documentation

Your module

Contains you form wizard code

Ctools' Object Cache

A non-volatile, temporary cache stored in the database

ctools_object_cache_set($obj, $name, $cache)

$cache = ctools_object_cache_get($obj, $name, $skip_cache = FALSE)

ctools_object_cache_clear($obj, $name)

Ctools' Form wizard tool

$output = ctools_wizard_multistep_form(

$form_info,

$step,

$form_state

);

The Forms

Standard FAPI forms

The data they operate on comes from $form_state

Can have validate functions

Must have submit functions

To save the data from $form_state[‘values’] to $form_state[‘whateveryoucallyourcacheobject’]

The CallbacksNext:

This function should take the submitted data and cache it for later use by the finish callback.

Finish:

This function should finalize all data.

Cancel:

This function should clean up any data that is cached.

Return:

This is often the same as the finish callback.

Common:

Defaults to: $form_info['id'] . _<callback> if it doesn't exist.

Params: &$form_state.

Demo and Code

Other Considerations

AJAX

The cancel and back buttons with required fields

Anonymous users

Auto caching ($form_info['auto cache'])

Next and finish callbacks not requiredUnless you want to change what the next form will be in the next callback, which is set thusly: $form_state[‘triggering element’][‘#next’] = $new_step;

Resources 1

http://oadaeh.net/presenting_at_drupalcamps

http://www.thecarneyeffect.co.uk/ctools-modal-wizard-multistep-form-using-ajax-drupal-7

http://internetdevels.com/blog/ctools-multistep-wizard-example

http://www.grasmash.com/article/building-multistep-registration-form-drupal-7-using-ctools

http://www.convert-control.de/en/help/ctools/wizard

Resources 2

Documentation:

Advanced help

sites/all/modules/ctools/includes/wizard.inc

Presentation:

http://www.angrydonuts.com/ctools-presentation-slides-and-example-code

Extending the tool:

http://drupal7ish.blogspot.com/2011/02/extending-chaos-tools-wizard.html

Questions?