Code examples for 7.x-2.x

Hi,
As promised in #2477741: Provide backwards compatibility with 7.x-1.x implementations, I've had a stab at writing up a couple of coding examples of using this module, version 7.x-2.x, because the README is out of date at the moment.
The js.api.php appears up to date, but its scope is not to provide a how-to guide.
This is a first attempt at that.
Hope it's useful.
Rik

High-performance JavaScript callback handler -- examples
========================================================


Example 1:
Improving the performance of custom JS calling Drupal
-----------------------------------------------------
Not using the JS module, you can instigate from your javascript a call to your
Drupal site like so:

    var data = new Object;
    data = ....; // your data

    jQuery.ajax({
      url: '/path/used/in/hook_menu',
      type: 'POST',
      dataType: 'json',
      data: data,
      success: function (serverData, textStatus, http) {
        // Either do nothing, or perhaps refresh the page like so:
        window.location.reload();
      },
      error: function (http, textStatus, error) {
        var msg = Drupal.t('Error: @status: @error (@code)',
          { '@status': textStatus, '@error': error, '@code': http.status }
        );
        if (window.console && window.console.log) {
          window.console.log(msg);
        }
        else {
          alert(msg);
        }
      },
    });

To use the JS module with the above, you first need to add a couple of pieces of
information as part of the data you POST back to Drupal:

    var data = new Object;
    data = ....; // your data
    data['js_module'] = 'YOURMODULE'; // the module receiving the data
    data['js_callback'] = 'CALLBACK_INFO'; // see below

Then to go with the above, implement hook_js_info() in YOURMODULE.module

/**
 * Implements hook_js_info().
 * With the js.module installed, and the .htaccess file edited to route
 * through js.php, this array defines what function to call when a POST is
 * received.
 * We're calling the same function as defined in hook_menu(), but using
 * a faster, more economic bootstrap phase, without hook_init().
 */
function YOURMODULE_js_info() {
  $js_info = array(
    'CALLBACK_INFO' => array(
      'bootstrap' => DRUPAL_BOOTSTRAP_SESSION, // the min. level you can get away with
      'callback function' => '...', // use function defined in hook_menu(),
      'dependencies' => array('MODULE1_YOU_NEED', 'MODULE2_YOU_NEED'),
      'skip init' => TRUE,
      'token' => FALSE, // only use FALSE if you want to bypass security, see js.api.php
    ),
  );
  return $js_info;
}

Now the 'callback function' does what it used to, but more efficiently. It may
store some of the POSTed data in the $_SESSION or on the database. As before,
if all went well, your javascript will see its success() function called.

Example 2:
Improving the performance of Drupal core AJAX calls (system/ajax)
-----------------------------------------------------------------
As you may know, you can instigate an AJAX call via the form API. Let's say you
want to create a form with a 'Find' button that does some work 'under the hood',
without refreshing the entire page. Instead a throbber spins and a 'Please
wait' message is shown.
Before using the drupal.org/project/js module your code will look something like
the following.

  function YOURMODULE_find_form($form, &$form_state) {
    // ... add some form elements ...

    $form['#attributes']['id'] = drupal_html_id('SOME_FORMID_YOU_LIKE');

    // Add an AJAX submit button, labeled 'Find'
    $form['find'] = array(
      '#type' => 'button', // or 'submit' if you want to call '#submit' too
      '#value' => t('Find'),
      '#ajax' => array(
        'callback' => '_YOURMODULE_process_ajax',
        'wrapper' => $form['#attributes']['id'],
        'progress' => array('type' => 'throbber'),
      ),
    );
    return $form;
  }

  function _YOURMODULE_process_ajax($form, &$form_state) {
    // ... do stuff outside the server
    // ... you could load additional JS, to be executed in the browser
    // ... you could invoke an external service that calls back to Drupal

    // ... change/ add some form elements to show progress, like a message ...
    $form['in-progress-message'] = array(
      '#prefix' => '<div class="message">',
      '#markup' => t('Please wait while we are processing your request.'),
      '#suffix' => '</div>',
      '#weight' => 10, // A weight corresponding to right spot on the form
    );

    return $form;
  }

You also need to implement hook_menu() to receive at the correct URL/path the
response of whatever your JS or external service posts to your site.

Note: the '#autocomplete_path' form field is a special case of the above with a
few tweaks (someone to elaborate on this)

The above technique works well but is subject to improvement in the same way
as the first example, because the external service or JS is unlikely to require
more than the minimal bootstrapping and is unlikely to require any hook_init()
implementations being called.

Applying JS to the above could goes like this:

   ... someone to fill this out, any takers? ...

That's how far I got based on my limited experience.
Really needs an expert to correct where necessary and complete it.