Dialogs

There are three main types of dialogs:

• Single select dialogs: These dialogs allow you to select a single item from a list, or change an existing selection e.g. the three dialogs in Positions tab in the user profile
• Multi select dialogs: These dialogs allow you to add item(s) to an existing list e.g adding Competencies to a Learning Plan
• Custom dialogs: Random static or dynamic pages loaded inside the a Totara dialog e.g. responding to Alerts

The two select dialogs above can either merely 'select' elements which then need to be saved in the page below, or they may 'select and save'. The page below will is the important interface in terms of indicating saved or 'yet to be saved' nature of the selected element(s). For look and feel definitions of the select dialogs see selecting elements.

Front end (Javascript)

• Uses the JQuery dialog Javascript, extended in the file local/js/lib/dialogs.js.php
• Javascript files should be loaded using the function local_js() in local/js/lib/setup.php
• Two main classes, totaraDialog and totaraDialog_handler()
• totaraDialog is the class that handles the dialog frame, opening/closing the dialog, the buttons, and also loading content.
• totaraDialog_handler() is the function that handles all the logic and the button actions. This is the class you need to extend if you want to customize the Javascript side of the dialog.
• New dialogs can be generated quickly using the functions at the bottom of the file

Setting up a custom dialog

• All dialog objects are added to the global array totaraDialogs (indexed by their unique name)
• Dialogs are only created once per page load, and are simply opened/closed (not recreated)
• JS should be put inside .php files so you have access to things like optional_param(), $CFG, and get_string()

<nowiki>
  (function() {
      /**
       * Wrapping the code in a function block means variables created inside this scope are cleaned up once the block has executed
       */
  
      // Choose a dialog name unique to this page
      var name = 'addremove';
  
      // Setup the handler class
      var handler = new totaraDialog_handler();
  
      totaraDialogs[name] =  new totaraDialog(
          'name',                   // used for CSS, ID's etc
          /*
            ID of an element on the page to bind to. the dialog's open() function will be called via the "click" handler.
            If you would like to set up this functionality yourself (e.g. want to trigger via something other than
            "click", set this parameter to default)
          */
          'show-'+name+'-dialog',
          {
              buttons: {                                         // Buttons to appear at base of dialog
                    '<?php echo get_string('cancel') ?>': function() { handler._cancel(); },
                    // Add more dialogs here, NOTE: they appear in the opposite order due to floating
              },
              title: '<h2><?php echo get_string('addremove'); ?></h2>',   // Title of dialog (remember the H2 tags!)
          },
          'http://example.com/dialog.php',           // Default URL to load
          handler                                    // Assign the handler
      );
  })();
</nowiki>

Back end (PHP)

Content classes can be used to speed up development of new dialogs very quickly. A number exist already. See local/dialogs/

If you are creating a new type of dialog, especially a treeview based dialog you would be wise to extend local/dialogs/dialog_content.class