| 1 |
/* $Id: README.txt,v 1.3 2009/06/15 21:03:16 smk Exp $ */
|
| 2 |
|
| 3 |
-- SUMMARY --
|
| 4 |
|
| 5 |
JavaScript callback handler is an interim solution for high-performance querying
|
| 6 |
of contents including (but not limited to) AHAH, AJAX, JSON, XML, etc.
|
| 7 |
|
| 8 |
Apache benchmarks speak for itself:
|
| 9 |
|
| 10 |
Using index.php as usual:
|
| 11 |
ab -n20 -c1 http://example.com/index.php?q=js/mymodule/callback
|
| 12 |
Requests per second: 2.24 [#/sec] (mean)
|
| 13 |
Time per request: 446.846 [ms] (mean)
|
| 14 |
|
| 15 |
Using js.php:
|
| 16 |
ab -n20 -c1 http://example.com/js.php?q=js/mymodule/callback
|
| 17 |
Requests per second: 16.84 [#/sec] (mean)
|
| 18 |
Time per request: 59.371 [ms] (mean)
|
| 19 |
|
| 20 |
Note that this module does nothing on itself.
|
| 21 |
|
| 22 |
For a full description visit the project page:
|
| 23 |
http://drupal.org/project/js
|
| 24 |
Bug reports, feature suggestions and latest developments:
|
| 25 |
http://drupal.org/project/issues/js
|
| 26 |
|
| 27 |
|
| 28 |
-- INSTALLATION --
|
| 29 |
|
| 30 |
* Install as usual, see http://drupal.org/node/70151 for further information.
|
| 31 |
|
| 32 |
* Copy js.php to the root directory of your Drupal installation.
|
| 33 |
|
| 34 |
* Enable clean URLs.
|
| 35 |
|
| 36 |
* Add the following lines in front of the existing RewriteRules in your
|
| 37 |
.htaccess file:
|
| 38 |
|
| 39 |
# Rewrite JavaScript callback URLs of the form 'js.php?q=x'.
|
| 40 |
RewriteCond %{REQUEST_FILENAME} !-f
|
| 41 |
RewriteCond %{REQUEST_FILENAME} !-d
|
| 42 |
RewriteCond %{REQUEST_URI} ^\/js\/.*
|
| 43 |
RewriteRule ^(.*)$ js.php?q=$1 [L,QSA]
|
| 44 |
|
| 45 |
|
| 46 |
-- DEVELOPER INFORMATION --
|
| 47 |
|
| 48 |
This module requires an Apache RewriteRule in your .htaccess file to point all
|
| 49 |
paths starting with js/ to js.php rather than index.php. The 2nd argument
|
| 50 |
following js/ determines the implementing module, which must implement hook_js()
|
| 51 |
for security reasons. Apart from security, modules may also specify another
|
| 52 |
bootstrap level than the default DRUPAL_BOOTSTRAP_PATH, and additionally
|
| 53 |
required includes files and module dependencies to load.
|
| 54 |
|
| 55 |
As an example, we'll let example.module expose its function
|
| 56 |
example_somefunction() to js.php. Its hook_js() implementation might look like
|
| 57 |
this:
|
| 58 |
|
| 59 |
<code>
|
| 60 |
function example_js() {
|
| 61 |
return array(
|
| 62 |
'somefunction' => array(
|
| 63 |
'callback' => 'example_somefunction',
|
| 64 |
'includes' => array('theme', 'unicode'),
|
| 65 |
'dependencies' => array('locale', 'filter', 'user'),
|
| 66 |
),
|
| 67 |
);
|
| 68 |
}
|
| 69 |
</code>
|
| 70 |
|
| 71 |
The hook_js() implementation above makes JS accept the following URL:
|
| 72 |
|
| 73 |
http://example.com/js/example/somefunction.
|
| 74 |
^ ^
|
| 75 |
module name -| |
|
| 76 |
info array key -|
|
| 77 |
|
| 78 |
When called, it loads the requested include files and modules and calls the
|
| 79 |
callback function.
|
| 80 |
|
| 81 |
Note that it is wise to also register a corresponding menu path in hook_menu()
|
| 82 |
to provide fallback functionality when js.php is not available:
|
| 83 |
|
| 84 |
<code>
|
| 85 |
$items[] = array(
|
| 86 |
'path' => 'js/example/somefunction',
|
| 87 |
'callback' => 'example_somefunction',
|
| 88 |
'type' => MENU_CALLBACK,
|
| 89 |
);
|
| 90 |
</code>
|
| 91 |
|
| 92 |
As stated above, js.php bootstraps Drupal to DRUPAL_BOOTSTRAP_PATH and includes
|
| 93 |
common.inc and locale.inc. This means that url(), l(), and t() functions are
|
| 94 |
available (t() lacks translation though, since that would require locale.module
|
| 95 |
to be loaded. This can be easily "fixed" by adding locale to the dependencies
|
| 96 |
array). Theme functions and potentially required functions of other modules,
|
| 97 |
however, are not available by default, which is the main reason for the speed
|
| 98 |
gain of js.php. Since the session has been initialized, the global $user
|
| 99 |
object is also available (but may not be fully loaded).
|
| 100 |
|
| 101 |
Please note that js.php does NOT perform access checks like Drupal's menu
|
| 102 |
system. If required, each callback function needs to do this on its own.
|
| 103 |
|
| 104 |
js.php outputs the return value of the callback function using drupal_to_js().
|
| 105 |
To use a custom output format, output the data on your own and exit()
|
| 106 |
afterwards, or simply return nothing.
|
| 107 |
|
| 108 |
|
| 109 |
-- CREDITS --
|
| 110 |
|
| 111 |
Authors:
|
| 112 |
* Daniel F. Kudwien (sun) - http://drupal.org/user/54136
|
| 113 |
* Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898
|
| 114 |
|
| 115 |
This project has been sponsored by UNLEASHED MIND.
|
| 116 |
Specialized in consulting and planning of Drupal powered sites, UNLEASHED
|
| 117 |
MIND offers installation, development, theming, customization, and hosting
|
| 118 |
to get you started. Visit http://www.unleashedmind.com for more information.
|
| 119 |
|
Parent Directory
| 
Revision Log
| 
Revision Graph