[Summary view] [Print] [Text view]

   1  <!-- $Id: modal.html,v 1.1.2.1 2010/09/08 21:10:12 merlinofchaos Exp $ -->
   2  CTools provides a simple modal that can be used as a popup to place forms. It differs from the normal modal frameworks in that it does not do its work via an iframe. This is both an advantage and a disadvantage. The iframe simply renders normal pages in a sub-browser and they can do their thing. That makes it much easier to put arbitrary pages and forms in a modal. However, the iframe is not very good at actually communicating changes to the main page, so you cannot open the modal, have it do some work, and then modify the page. 
   3  
   4  <h3>Invoking the modal</h3>
   5  
   6  The basic form of the modal can be set up just by including the javascript and adding the proper class to a link or form that will open the modal. To include the proper javascript, simply include the library and call the add_js function:
   7  
   8  <pre>
   9  ctools_include('modal');
  10  ctools_modal_add_js();
  11  </pre>
  12  
  13  You can have links and buttons bound to use the modal by adding the class ctools-use-modal. For convenience, there is a helper function to try and do this, though it's not great at doing all links so using this is optional:
  14  
  15  <pre>
  16  /**
  17   * Render an image as a button link. This will automatically apply an AJAX class
  18   * to the link and add the appropriate javascript to make this happen.
  19   *
  20   * @param $image
  21   *   The path to an image to use that will be sent to theme('image') for rendering.
  22   * @param $dest
  23   *   The destination of the link.
  24   * @param $alt
  25   *   The alt text of the link.
  26   * @param $class
  27   *   Any class to apply to the link. @todo this should be a options array.
  28   */
  29  function ctools_modal_image_button($image, $dest, $alt, $class = '') {
  30    return ctools_ajax_text_button(theme('image', $image), $dest, $alt, $class, 'ctools-use-modal');
  31  }
  32  
  33  /**
  34   * Render text as a link. This will automatically apply an AJAX class
  35   * to the link and add the appropriate javascript to make this happen.
  36   *
  37   * Note: 'html' => true so be sure any text is vetted! Chances are these kinds of buttons will
  38   * not use user input so this is a very minor concern.
  39   *
  40   * @param $image
  41   *   The path to an image to use that will be sent to theme('image') for rendering.
  42   * @param $dest
  43   *   The destination of the link.
  44   * @param $alt
  45   *   The alt text of the link.
  46   * @param $class
  47   *   Any class to apply to the link. @todo this should be a options array.
  48   */
  49  function ctools_modal_text_button($text, $dest, $alt, $class = '') {
  50    return ctools_ajax_text_button($text, $dest, $alt, $class, 'ctools-use-modal');
  51  }
  52  </pre>
  53  
  54  Like with all CTools' AJAX functionality, the href of the link will be the destination, with any appearance of /nojs/ converted to /ajax/.
  55  
  56  
  57  For submit buttons, however, the URL may be found a different, slightly more complex way. If you do not wish to simply submit the form to the modal, you can create a URL using hidden form fields. The ID of the item is taken and -url is appended to it to derive a class name. Then, all form elements that contain that class name are founded and their values put together to form a URL.
  58  
  59  For example, let's say you have an 'add' button, and it has a select form item that tells your system what widget it is adding. If the id of the add button is edit-add, you would place a hidden input with the base of your URL in the form and give it a class of 'edit-add-url'. You would then add 'edit-add-url' as a class to the select widget allowing you to convert this value to the form without posting. If no URL is found, the action of the form will be used and the entire form posted to it.
  60  
  61  <h3>Customizing the modal</h3>
  62  
  63  If you do not wish to use the default modal, the modal can be customized by creating an array of data to define a customized modal. To do this, you add an array of info to the javascript settings to define the customizations for the modal and add an additional class to your modal link or button to tell it which modal to use.
  64  
  65  First, you need to create a settings array. You can do this most easily with a bit of PHP:
  66  
  67  <pre>
  68    drupal_add_js(array(
  69      'my-modal-style' => array(
  70        'modalSize' => array(
  71          'type' => 'fixed',
  72          'width' => 250,
  73          'height' => 250,
  74        ),
  75      ),
  76    ), 'setting');
  77  </pre>
  78  
  79  The key to the array above (in this case, my-modal-style) is the identifier to your modal theme. You can have multiple modal themes on a page, so be sure to use an ID that will not collide with some other module's use. Using your module or theme as a prefix is a good idea.
  80  
  81  Then, when adding the ctools-use-modal class to your link or button, also add the following class: ctools-modal-ID (in the example case, that would be ctools-modal-my-modal-style).
  82  
  83  modalSize can be 'fixed' or 'scale'. If fixed it will be a raw pixel value; if 'scale' it will be a percentage of the screen.
  84  
  85  You can set:
  86  <ul>
  87  <li> <b>modalSize</b>: an array of data to control the sizing of the modal. It can contain:
  88  <ul>
  89  <li> <b>type</b>: Either <i>fixed</i> or <i>scale</i>. If fixed, the modal will always be a fixed size. If <i>scale</i> the modal will scale to a percentage of the browser window. <i>Default: scale</i>.
  90  <li> <b>width</b>: If <i>fixed</i> the width in pixels. If <i>scale</i> the percentage of the screen expressed as a number less than zero. (For 80 percent, use .8, for example). <i>Default: .8</i></li>
  91  <li> <b>height</b>: If <i>fixed</i> the height in pixels. If <i>scale</i> the percentage of the screen expressed as a number less than zero. (For 80 percent, use .8, for example). <i>Default: .8</i></li>
  92  <li> <b>addWidth</b>: Any additional width to add to the modal in pixels. Only useful if the type is scale. <i>Default: 0</i></li>
  93  <li> <b>addHeight</b>: Any additional height to add to the modal in pixels. Only useful if the type is scale. <i>Default: 0</i></li>
  94  <li> <b>contentRight</b>: The number of pixels to remove from the content inside the modal to make room for scroll bar and decorations. <i>Default: 25</i></li>
  95  <li> <b>contentBottom</b>: The number of pixels to remove from the content inside the modal to make room for scroll bar and decorations. <i>Default: 45</i></li>
  96  </ul>
  97  </li>
  98  <li> <b>modalTheme</b>: The Drupal javascript themable function which controls how the modal will be rendered. This function must be in the <i>Drupal.theme.prototype</i> namespace. If you set this value, you must include a corresponding function in a javascript file and use drupal_add_js() to add that file. <i>Default: CToolsModalDialog</i>
  99  <pre>
 100    Drupal.theme.prototype.CToolsModalDialog = function () {
 101      var html = ''
 102      html += '  &lt;div id="ctools-modal"&gt;'
 103      html += '    &lt;div class="ctools-modal-content"&gt;' // panels-modal-content
 104      html += '      &lt;div class="modal-header"&gt;';
 105      html += '        &lt;a class="close" href="#"&gt;';
 106      html +=            Drupal.CTools.Modal.currentSettings.closeText + Drupal.CTools.Modal.currentSettings.closeImage;
 107      html += '        &lt;/a&gt;';
 108      html += '        &lt;span id="modal-title" class="modal-title"&gt;&nbsp;&lt;/span&gt;';
 109      html += '      &lt;/div&gt;';
 110      html += '      &lt;div id="modal-content" class="modal-content"&gt;';
 111      html += '      &lt;/div&gt;';
 112      html += '    &lt;/div&gt;';
 113      html += '  &lt;/div&gt;';
 114  
 115      return html;
 116    }
 117  </pre></li>
 118  <li> <b>throbberTheme</b>: The Drupal javascript themable function which controls how the modal throbber will be rendered. This function must be in the <i>Drupal.theme.prototype</i> namespace. If you set this value, you must include a corresponding function in a javascript file and use drupal_add_js() to add that file. <i>Default: CToolsModalThrobber</i>
 119  <pre>
 120    Drupal.theme.prototype.CToolsModalThrobber = function () {
 121      var html = '';
 122      html += '  &lt;div id="modal-throbber"&gt;';
 123      html += '    &lt;div class="modal-throbber-wrapper"&gt;';
 124      html +=        Drupal.CTools.Modal.currentSettings.throbber;
 125      html += '    &lt;/div&gt;';
 126      html += '  &lt;/div&gt;';
 127  
 128      return html;
 129    };
 130  </pre>
 131  </li>
 132  <li> <b>modalOptions</b>: The options object that's sent to Drupal.CTools.Modal.modalContent. Can contain any CSS settings that will be applied to the modal backdrop, in particular settings such as <b>opacity</b> and <b>background</b>. <i>Default: array('opacity' => .55, 'background' => '#fff');</i></li>
 133  <li> <b>animation</b>: Controls how the modal is animated when it is first drawn. Either <b>show</b>, <b>fadeIn</b> or <b>slideDown</b>. <i>Default: show</i></li>
 134  <li> <b>animationSpeed</b>: The speed of the animation, expressed either as a word jQuery understands (slow, medium or fast) or a number of milliseconds for the animation to run. <i>Defaults: fast</i></li>
 135  <li><b>closeText</b>: The text to display for the close button. Be sure to wrap this in t() for translatability. <i>Default: t('Close window')</i></li>
 136  <li><b>closeImage</b>: The image to use for the close button of the modal. <i>Default: theme('image', ctools_image_path('icon-close-window.png'), t('Close window'), t('Close window'))</i></li>
 137  <li><b>loadingText</b>: The text to display for the modal title during loading, along with the throbber. Be sure to wrap this in t() for translatability. <i>Default: t('Close window')</i></li>
 138  <li><b>throbber</b>: The HTML to display for the throbber image. You can use this instead of CToolsModalThrobber theme if you just want to change the image but not the throbber HTML. <i>Default: theme('image', ctools_image_path('throbber.gif'), t('Loading...'), t('Loading'))</i></li>
 139  <li>
 140  </ul>
 141  
 142  <h3>Rendering within the modal</h3>
 143  To render your data inside the modal, you need to provide a page callback in your module that responds more or less like a normal page.
 144  
 145  In order to handle degradability, it's nice to allow your page to work both inside and outside of the modal so that users whose javascript is turned off can still use your page. There are two ways to accomplish this. First, you can embed 'nojs' as a portion of the URL and then watch to see if that turns into 'ajax' when the link is clicked. Second, if you do not wish to modify the URLs, you can check $_POST['js'] or $_POST['ctools_js'] to see if that flag was set. The URL method is the most flexible because it is easy to send the two links along completely different paths if necessary, and it is also much easier to manually test your module's output by manually visiting the nojs URL. It's actually quite difficult to do this if you have to set $_POST['js'] to test.
 146  
 147  In your hook_menu, you can use the a CTools' AJAX convenience loader to help:
 148  
 149  <pre>
 150    $items['ctools_ajax_sample/%ctools_js/login'] = array(
 151        'title' => 'Login',
 152        'page callback' => 'ctools_ajax_sample_login',
 153        'page arguments' => array(1),
 154        'access callback' => TRUE,
 155        'type' => MENU_CALLBACK,
 156    );
 157  </pre>
 158  
 159  The first argument to the page callback will be the result of ctools_js_load() which will return TRUE if 'ajax' was the string, and FALSE if anything else (i.e, nojs) is the string. Which means you can then declare your function like this:
 160  
 161  <pre>
 162  function ctools_ajax_sample_login($js) {
 163    if ($js) {
 164      // react with the modal
 165    }
 166    else {
 167      // react without the modal
 168    }
 169  }
 170  </pre>
 171  
 172  If your modal does not include a form, rendering the output you wish to give the user is just a matter of calling the modal renderer with your data:
 173  
 174  <pre>
 175  function ctools_ajax_hello_world($js) {
 176    $title = t('Greetings');
 177    $output = '&lt;p&gt;' . t('Hello world') . ''&lt;/p&gt;';
 178    if ($js) {
 179      ctools_modal_render($title, $output);
 180    }
 181    else {
 182      drupal_set_title($title);
 183      return $output;
 184    }
 185  }
 186  </pre>
 187  
 188  If you need to do more than just render your modal, you can use a CTools $commands array. See the function ctools_modal_render() for more information on what you need to do here.
 189  
 190  If you are displaying a form -- and the vast majority of modals display forms -- then you need to do just slightly more. Fortunately there is the ctools_modal_form_wrapper() function:
 191  
 192  <pre>
 193    ctools_include('modal');
 194    ctools_include('ajax');
 195    $form_state = array(
 196      'title' => t('Title of my form'),
 197      'ajax' => $js,
 198    );
 199    $output = ctools_modal_form_wrapper('my_form', $form_state);
 200    // There are some possible states after calling the form wrapper:
 201    // 1) We are not using $js and there is form output to be rendered.
 202    // 2) We are using $js and the form was successfully submitted and
 203    //    we need to dismiss the modal.
 204    // Most other states are handled automatically unless you set flags in
 205    // $form_state to avoid handling them, so we only deal with those two
 206    // states.
 207    if (empty($output) && $js) {
 208      $commands = array();
 209      $commands[] = ctools_modal_command_dismiss(t('Login Success');
 210      // In typical usage you will do something else here, such as update a
 211      // div with HTML or redirect the page based upon the results of the modal
 212      // form.
 213      ctools_ajax_render($commands);
 214    }
 215  
 216    // Otherwise, just return the output.
 217    return $output;
 218  </pre>
 219  
 220  You can also use CTools' form wizard inside the modal. You do not need to do much special beyond setting $form_state['modal'] = TRUE in the wizard form; it already knows how to handle the rest.