[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: modal.inc,v 1.7.2.6 2010/09/08 21:10:12 merlinofchaos Exp $
   3  
   4  /**
   5   * @file
   6   * Implement a modal form using AJAX.
   7   *
   8   * The modal form is implemented primarily from mc.js; this contains the
   9   * Drupal specific stuff to use it. The modal is fairly generic and can
  10   * be activated mostly by setting up the right classes, but if you are
  11   * using the modal you must include links to the images in settings,
  12   * because the javascript does not inherently know where the images are
  13   * at.
  14   *
  15   * You can accomplish this with this PHP code:
  16   * @code {
  17   *   ctools_include('modal');
  18   *   ctools_modal_add_js();
  19   * }
  20   *
  21   * You can have links and buttons bound to use the modal by adding the
  22   * class ctools-use-modal.
  23   *
  24   * For links, the href of the link will be the destination, with any
  25   * appearance of /nojs/ converted to /ajax/.
  26   *
  27   * For submit buttons, however, the URL is found a different, slightly
  28   * more complex way. The ID of the item is taken and -url is appended to
  29   * it to derive a class name. Then, all form elements that contain that
  30   * class name are founded and their values put together to form a
  31   * URL.
  32   *
  33   * For example, let's say you have an 'add' button, and it has a select
  34   * form item that tells your system what widget it is adding. If the id
  35   * of the add button is edit-add, you would place a hidden input with
  36   * the base of your URL in the form and give it a class of 'edit-add-url'.
  37   * You would then add 'edit-add-url' as a class to the select widget
  38   * allowing you to convert this value to the form without posting.
  39   *
  40   * If no URL is found, the action of the form will be used and the entire
  41   * form posted to it.
  42   */
  43  
  44  function ctools_modal_add_js() {
  45    // Provide a gate so we only do this once.
  46    static $done = FALSE;
  47    if ($done) {
  48      return;
  49    }
  50  
  51    $settings = array(
  52      'CToolsModal' => array(
  53        'loadingText' => t('Loading...'),
  54        'closeText' => t('Close Window'),
  55        'closeImage' => theme('image', ctools_image_path('icon-close-window.png'), t('Close window'), t('Close window')),
  56        'throbber' => theme('image', ctools_image_path('throbber.gif'), t('Loading...'), t('Loading')),
  57      ),
  58    );
  59  
  60    drupal_add_js($settings, 'setting');
  61    drupal_add_js('misc/jquery.form.js');
  62    ctools_add_js('ajax-responder');
  63    ctools_add_js('modal');
  64  
  65    ctools_add_css('modal');
  66    $done = TRUE;
  67  }
  68  
  69  /**
  70   * @todo this is deprecated
  71   */
  72  function ctools_modal_add_plugin_js($plugins) {
  73    $css = array();
  74    $js = array(drupal_get_path('module', 'ctools') . '/js/dependent.js' => TRUE);
  75    foreach ($plugins as $subtype) {
  76      if (isset($subtype['js'])) {
  77        foreach ($subtype['js'] as $file) {
  78          if (file_exists($file)) {
  79            $js[$file] = TRUE;
  80          }
  81          else if (file(exists($subtype['path'] . '/' . $file))) {
  82            $js[$subtype['path'] . '/' . $file] = TRUE;
  83          }
  84        }
  85      }
  86      if (isset($subtype['css'])) {
  87        foreach ($subtype['css'] as $file) {
  88          if (file_exists($file)) {
  89            $css[$file] = TRUE;
  90          }
  91          else if (file(exists($subtype['path'] . '/' . $file))) {
  92            $css[$subtype['path'] . '/' . $file] = TRUE;
  93          }
  94        }
  95      }
  96    }
  97  
  98    foreach (array_keys($js) as $file) {
  99      drupal_add_js($file);
 100    }
 101    foreach (array_keys($css) as $file) {
 102      drupal_add_css($file);
 103    }
 104  }
 105  
 106  /**
 107   * Place HTML within the modal.
 108   *
 109   * @param $title
 110   *   The title of the modal.
 111   * @param $html
 112   *   The html to place within the modal.
 113   */
 114  function ctools_modal_command_display($title, $html) {
 115    return array(
 116      'command' => 'modal_display',
 117      'title' => $title,
 118      'output' => $html,
 119    );
 120  }
 121  
 122  /**
 123   * Dismiss the modal.
 124   */
 125  function ctools_modal_command_dismiss() {
 126    return array(
 127      'command' => 'modal_dismiss',
 128    );
 129  }
 130  
 131  /**
 132   * Display loading screen in the modal
 133   */
 134  function ctools_modal_command_loading() {
 135    return array(
 136      'command' => 'modal_loading',
 137    );
 138  }
 139  
 140  /**
 141   * Render an image as a button link. This will automatically apply an AJAX class
 142   * to the link and add the appropriate javascript to make this happen.
 143   *
 144   * @param $image
 145   *   The path to an image to use that will be sent to theme('image') for rendering.
 146   * @param $dest
 147   *   The destination of the link.
 148   * @param $alt
 149   *   The alt text of the link.
 150   * @param $class
 151   *   Any class to apply to the link. @todo this should be a options array.
 152   */
 153  function ctools_modal_image_button($image, $dest, $alt, $class = '') {
 154    return ctools_ajax_text_button(theme('image', $image), $dest, $alt, $class, 'ctools-use-modal');
 155  }
 156  
 157  /**
 158   * Render text as a link. This will automatically apply an AJAX class
 159   * to the link and add the appropriate javascript to make this happen.
 160   *
 161   * Note: 'html' => true so be sure any text is vetted! Chances are these kinds of buttons will
 162   * not use user input so this is a very minor concern.
 163   *
 164   * @param $image
 165   *   The path to an image to use that will be sent to theme('image') for rendering.
 166   * @param $dest
 167   *   The destination of the link.
 168   * @param $alt
 169   *   The alt text of the link.
 170   * @param $class
 171   *   Any class to apply to the link. @todo this should be a options array.
 172   */
 173  function ctools_modal_text_button($text, $dest, $alt, $class = '') {
 174    return ctools_ajax_text_button($text, $dest, $alt, $class, 'ctools-use-modal');
 175  }
 176  
 177  /**
 178   * Wrap a form so that we can use it properly with AJAX. Essentially if the
 179   * form wishes to render, it automatically does that, otherwise it returns
 180   * so we can see submission results.
 181   *
 182   * @return
 183   *   The output of the form, if it was rendered. If $form_state['ajax']
 184   *   is set, this will use ctools_modal_form_render so it will be
 185   *   a $command object suitable for ctools_ajax_render already.
 186   *
 187   *   The return will be NULL if the form was successfully submitted unless
 188   *   you specifically set re_render = TRUE. If ajax is set the
 189   *   form will never be redirected.
 190   */
 191  function ctools_modal_form_wrapper($form_id, &$form_state) {
 192    ctools_include('form');
 193    // This won't override settings already in.
 194    $form_state += array(
 195      're_render' => FALSE,
 196      'no_redirect' => !empty($form_state['ajax']),
 197    );
 198  
 199    $output = ctools_build_form($form_id, $form_state);
 200    if (!empty($form_state['ajax']) && empty($form_state['executed'])) {
 201      return ctools_modal_form_render($form_state, $output);
 202    }
 203  
 204    return $output;
 205  }
 206  
 207  /**
 208   * Render a form into an AJAX display.
 209   */
 210  function ctools_modal_form_render($form_state, $output) {
 211    $title = empty($form_state['title']) ? drupal_get_title() : $form_state['title'];
 212  
 213    // If there are messages for the form, render them.
 214    if ($messages = theme('status_messages')) {
 215      $output = '<div class="messages">' . $messages . '</div>' . $output;
 216    }
 217  
 218    $commands = array();
 219    if (isset($form_state['js settings'])) {
 220      $commands[] = ctools_ajax_command_settings($form_state['js settings']);
 221    }
 222  
 223    $commands[] = ctools_modal_command_display($title, $output);
 224    return $commands;
 225  }
 226  
 227  /**
 228   * Perform a simple modal render and immediately exit.
 229   *
 230   * This is primarily used for error displays, since usually modals will
 231   * contain forms.
 232   */
 233  function ctools_modal_render($title, $output) {
 234    $commands = array();
 235    $commands[] = ctools_modal_command_display($title, $output);
 236    ctools_include('ajax');
 237    ctools_ajax_render($commands);
 238  }