jDog

jDog unleashes the Drupal watchdog in jQuery. This is the official documentation page.

jDog gives you all the advantages of Drupal watchdog recording plus email notifications direct in your jQuery and Javascript. The supplied jDog Javascript function, automatically installed by jDog, posts your request to your Web site using Ajax. The jDog module accepts the Ajax request and places the request into the Drupal watchdog function. Optionally, jDog will send an email notification.

Download

Download jDog from my Drupal sandpit at http://drupal.org/sandbox/peter/1414906.

Objectives

• Send watchdog messages from jQuery.
• Optionally:
  • Send email alerts for errors.
• Work without anyone visiting the configuration or permissions pages.
• Add all project bloat as optional modules.

Method

jDog adds Javascript functions to your Web page. Use the Javascript functions to send messages to your Drupal web site. The jDog module accepts your request, reads the jDog configuration, sets a watchdog message for every incoming message, and optionally sends email for some messages.

Javascript functions

you get the following Javascript functions. The first is an exact copy of the Drupal watchdog function with an added email option. The last is a simplified email request using the same format as watchdog. In the middle are simplified Javascript functions for the the different severity levels.

jdog(type, message, variables, severity, link, email);
jdog_alert(type, message, variables, link, email);
jdog_critical(type, message, variables, link, email);
jdog_debug(type, message, variables, link, email);
jdog_emergency(type, message, variables, link, email);
jdog_error(type, message, variables, link, email);
jdog_info(type, message, variables, link, email);
jdog_notice(type, message, variables, link, email);
jdog_warning(type, message, variables, link, email);
jdog_email(subject, message, variables, email);

Code

The code in the sandbox is missing a direct download because I am experimenting with Git access. Use Git or the drupal.org Git browser to access jDog.

There are three main files in jDog. There is the Drupal module .info file, jdog.info, as needed in all modules. The functions you use in Javascript and jQuery are in jdog.js. The processing module is jdog.module.

jDog creates the Ajax connection as a menu entry callback. Assuming your Web site is example.com, the URL is http://example.com/jdog. If you access the page from the Web, the page returns a small amount of documentation pointing back to this page. You can see the small documentation page at ka.tl/jdog. the jDog administration page will provide the option to change the page URL.

Watchdog

The following line of code is the definition of the Drupal watchdog function in Drupal 7.
watchdog($type, $message, $variables = array(), $severity = WATCHDOG_NOTICE, $link = NULL);

The equivalent in your Javascript is shown next.
jdog($type, $message, $variables, $severity, $link);

jDog adds one extra parameter to force the sending on an email.
jdog(type, message, variables, severity, link, email);

Severity levels

The following table lists the severity levels handled by Drupal watchdog. jDog handles all these severity levels.

jDog offers a shortcut. When you want to send an error, you can use the following style of function. There is a shortcut function for every severity level.
jdog_error($type, $message, $variables, $link);

Send email

You can set jDog to automatically send an email for a severity level. Visit Administration » Configuration » jDog, or admin/config/jdog, to configure jDog. If you want an email send for errors, add an email address for errors.

When you want to send an email for one error, you can add an option to the end of your jDog request as shown next.
jdog_error($type, $message, $variables, $link, 'yes');

Javascript arrays for PHP programmers

Javascript has arrays with numeric indexes, the same as PHP. Unlike PHP, Javascript does not have arrays with text indexes. PHP arrays with text indexes are called hashes and a variety of other names. You emulate text arrays using Javascript object notation. The following Javascript example uses the Javascript object notation to emulated a text indexed array, in this case for the watchdog variables list.

jdog('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'});

For people with PHP experience and not much Javascript experience, the example would be written in PHP as:

jdog('Jdog Ajax call', 'Hello @to. From @from', array('to' => 'Joe', 'from' => 'me'));

A real watchdog example in PHP would look like the following.
jdog('Jdog Ajax call', 'Hello @to. From @from', array('@to' => 'Joe', '@from' => 'me'));

Javascript opject notation does not let us use the @ so we leave out the @ in the jDog variables list and jDog adds the @ back at the server end. jDog will eventually let you choose something other than @.

Javascript examples

Simple watchdog example

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog. Run your Javascript then look in the watchdog report in your Drupal web site.
jdog('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'});

Report an error

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with one change, the severity level is set to error by using the jdog_error() function.
jdog_error('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'});

Another way to report an error

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with one change, the severity level is set to error. This time we set the severity using a parameter. This is a good option when you want the severity level set by your code.
var severity = 'error';
jdog('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'}, severity);

Send a warning

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with one change, the severity level is set to warning.
jdog_warning('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'});

Send a warning with a link added

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with two changes, the severity level is set to warning and there is a link supplied. Read the Drupal documentation on watchdog() to find out how the link is used, or just throw one in as a test.
jdog_warning('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'}, 'http://example/com');

Send a warning to the Web site administrator

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with two changes, the severity level is set to warning and there is an email request added. jDog will respond to 'yes', 'true', and '1'. If I consume enough caffeine, I might add 1.
jdog_warning('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'}, '', 'yes');

Send a warning to someone specific

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with two changes, the severity level is set to warning and there is an email address added. The email address processing code will be added to jDog after a couple of double shot espressos.
jdog_warning('Jdog Ajax call', 'Hello @to. From @from', {to: 'Joe', from: 'me'}, '', 'joe@example.com');

Send an email without all the watchdog junk

Install jDog then add the following to your Javascript. This is the example tested at ka.tl/jdog with a few small changes, the type string becomes a plain email subject, the severity level disappears, and there is an email address added. This part of the code will be refined after many espressos and the odd neck massage.
jdog_email('Jdog email test', 'Hello @to. From @from', {to: 'Joe', from: 'me'}, '', 'joe@example.com');