CTools Modal Windows - Part III

In the earlier parts of this series, I've shown you have to create a simple modal popup using the CTools framework, and I've explained a bit about how Drupal renders the modal. Now its time to get our hands dirty - let's put a form in our modal window. We'll put the node/add/article forum in a modal window.

We've already used hook_menu() to setup a callback for our modal, let's change it just a smidgen

<?php function mymodule_menu() {   $items['modal-test-callback/%ctools_js'] = array(     'page callback' => 'mymodule_modal_callback',     'page arguments' => array(1),     'access arguments' => array('create article content'),     'type' => MENU_CALLBACK,   );   return $items; } ?>

What's new here? First off, we've added a second argument to the url, %ctools_js. Drupal takes any piece of a menu path that begins with a % sign and passes it to an 'autoload function' by the same name. So for example, if a hook_menu() item has the path 'node/%node', and a user goes to the path 'node/1', 1 will be passed to the node_load() function, and the result will be passed in as an argument to the item's page callback. In our case, the second argument is passed to ctools_js_load(), which will help us to determine if the user has javascript enabled or not. If a user goes to the path 'modal-test-callback/nojs', the ctools_js_load() function will return fase. However, if a user goes to 'modal-test-callback/ajax', it will return true. There's also new page and access arguments; I'll leave you to the hook_menu() documentation to interpret those.

Let's review the code we used to create our module's defined block, with one small adjustment.

<?php function mymodule_block_info() {   $blocks['modal_test'] = array(     'info' => t('Modal Test Block'),   );   return $blocks; } function mymodule_block_view($block_name) {   if ($block_name == 'modal_test') {         ctools_include('modal');     ctools_include('ajax');     ctools_modal_add_js();         return array(       'subject' => t('Modal Test Block Title!'),       'content' => ctools_modal_text_button(t('Click Here!'),'modal-test-callback/nojs',t('Click Here!')),     );   } } ?>

See the previous articles in this series for explanations of these two functions. The one change I've made is the path in ctools_modal_text_button(). Notice the 'nojs' that has been included. This 'nojs' will be re-written by the ctools javascript, which will replace it with 'ajax'. It's our job to use this re-writing and the ctools_js_load() autoloader to make sure our site is accessible to users without javascript (i.e. screenreaders, etc).

Let's make some changes to our mymodule_modal_callback() so that it will bring up the article node form. I'll provide the full callback here, and then we'll dissect its pieces below.

<?php function mymodule_modal_callback($js = false) {   // If the user doesn't have javascript, redirect them to the normal node/add/article page   if (!$js) {     drupal_goto('node/add/article');   }   else {     // Javascript is on, prepare ctools modals.     ctools_include('ajax');     ctools_include('modal');     // Pull in the global user, and prepare a blank node to pass to the node     // add form.     global $user;     $node = (object) array('uid' => $user->uid, 'name' => (isset($user->name) ? $user->name : ''), 'type' => 'article', 'language' => LANGUAGE_NONE);     $node->title = NULL;     node_object_prepare($node);     // Add the node.pages.inc so that functions from the form can be used.     module_load_include('inc', 'node', 'node.pages');     // Prepare the form state, ctools reqruies ajax / title.  The node add form     // requires node.     $form_state = array(       'ajax' => true,       'title' => t('Add a new Article'),       'node' => $node,     );     // Do the ctools_modal_form_wrapping of the node form.  Returns a set of     // ajax commands in output.     $output = ctools_modal_form_wrapper('article_node_form', $form_state);     if (!empty($form_state['executed'])) {       // Add the responder javascript, required by ctools       ctools_add_js('ajax-responder');       // Create ajax command array, dismiss the modal window.       $output = array();       $output[] = ctools_modal_command_dismiss();     }     print ajax_render($output);     exit;   } } ?>

Let's start with the top of the function.

The single argument that we declared in our hook_menu() implementation gets passed through the ctools_load_js() autoload function, and comes in as a $js boolean. We check $js, and it's false, we send the user on their merry way to the regular node/add form. If the user has javascript, we'll do the fun modal stuff.

<?php // Javascript is on, prepare ctools modals.     ctools_include('ajax');     ctools_include('modal');     // Pull in the global user, and prepare a blank node to pass to the node     // add form.     global $user;     $node = (object) array('uid' => $user->uid, 'name' => (isset($user->name) ? $user->name : ''), 'type' => 'article', 'language' => LANGUAGE_NONE);     $node->title = NULL;     node_object_prepare($node);     // Add the node.pages.inc so that functions from the form can be used.     module_load_include('inc', 'node', 'node.pages'); ?>

These few lines are all prep for the heavy lifting below. The ctools_include() calls are always needed to use some of the CTools' modal functions. All of this node business comes right out of Drupal's core form handling for node forms; the form needs to be initialized with an empty node. Lastly, the node.pages.inc is included so that any functions that the node/add/form needs are available.

<?php // Prepare the form state, ctools reqruies ajax / title.  The node add form     // requires node.     $form_state = array(       'ajax' => true,       'title' => 'Add a new Person',       'node' => $node,     );     // Do the ctools_modal_form_wrapping of the node form.  Returns a set of     // ajax commands in output.     $commands = ctools_modal_form_wrapper('article_node_form', $form_state);     if (!empty($form_state['executed'])) {       // Add the responder javascript, required by ctools       ctools_add_js('ajax-responder');       // Create ajax command array, dismiss the modal window.       $commands = array();       $commands = ctools_modal_command_dismiss();     }     print ajax_render($commands);     exit; ?>

This is where the real CTools work is done. First, we prepare a $form_state array for the form. CTools requires that we set 'ajax' => true, and that we give the form a title. This title will be along the top of the modal window. The $node is passed in here, as its required by the node_form itself. We pass the name of the form we want to modalize, along with our $form_state we just built to ctools_modal_form_wrapper(). This function is a lot like drupal_get_form, but it does a lot more. It turns the form into an array of AJAX commands that will pull up the modal and render the form within it. It also wraps the form's usual behavior in special handling (i.e. not redirecting when the form is complete, error handling, etc).

If the $form_state['executed'] value isn't set, in other words, if the form has not yet been submitted, the $commands are passed directly ajax_render() and returned as JSON to be rendered by Drupal's usual AJAX handling. If the form has been executed, we return a different set of AJAX commands. In this case, we simply dismiss the modal, but we could do something cooler if we wanted. Like this:

<?php   $output = array();   $output[] = ctools_modal_command_dismiss();   $output[] = ajax_command_after('.ctools-use-modal',theme('status_messages')); ?>

This will output Drupal's usual messages right after the ctools modal button (using a jquery style selector). I invite you to play around with other ajax commands. For example, you could insert the newly created node on the page somewhere.

Whew, that was a pretty long explanation, and admittedly, the code is a little complex. Get some practice with using these modal windows, and you'll be able to spin them up in no time.

Original Article:

CTools Modal Windows - Part III