dialog_get_form()

This function is analogous to drupal_get_form() and provides a simple way to place a form in a dialog, without having to write a callback.

Example:

In a normal, non-dialog menu definition, you might do the following:

$item['foo/bar'] = array(
  'title' => 'Foo bar',
  'page callback' => 'drupal_get_form',
  'page arguments' => array('foo_bar_form'),
  ...
);

And now with this function you can create a similar menu item like this:

$item['foo/bar/%ctools_js'] = array(
  'title' => 'Foo bar',
  'page callback' => 'dialog_get_form',
  'page arguments' => array('foo_bar_form', 2),
  ...
);

dialog_get_form will handle all the js/non-js form building, passing on any additional arguments to the form builder. Upon form submission, the ajax response is created in one of the following ways:

1. If a function exists following the format of [form_id]_dialog_success, it will be called and should return the appropriate ajax commands array. This is very similar to creating a [form_id]_submit function, but only gets called when in an ajax context.
2. Otherwise, if the submit handler set a redirect path in the form state, then a redirect command is created.
3. And if all else fails, a simple reload command is issued.

Here is what the user login example looks like now.

function dialog_user_menu() {
  $items['user/login/%ctools_js'] = array(
    'title' => 'Log in',
    'page callback' => 'dialog_get_form',
    'page arguments' => array('user_login', 2),
    'access callback' => 'user_is_anonymous',
    'type' => MENU_CALLBACK,
    'file' => 'user.pages.inc',
    'file path' => drupal_get_path('module', 'user'),
  );
  return $items;
}

Thats it, just a menu declaration, no callback needed! Notice though, that you must take care to include the file where the form builder is located.