$Id$

Quotes:Random is a simple helper module to facilitate efficient retrieval of a
single quote from among those quotes which are visible to the anonymous user.
This is useful for showing a single random quote somewhere on the page, without
the overhead associated with "order by RAND()".

The four functions intended for general use are as follows:

/**
 * Returns the nid of a randomly selected quote.
 */
function randomquote_nid()

/**
 * Returns a randomly-selected quote (summary view), linked to its full node,
 * and classed as "randomquote-link" for easy styling.
 */
function randomquote_link()


/**
 * Replaces the contents of a single page element with a randomquote_link().
 * This enables cached pages to have dynamic random quotes.
 *
 * @param string $element
 *   The jquery selector for a DOM page element whose contents will be replaced.
 *
 * Example usage (in MYTHEME/template.php):
 *   function MYTHEME_preprocess_page(&$vars) {
 *     // Insert a random quote as footer text
 *     randomquote_js('#footer');
 *   }
 */
function randomquote_js($element) {

/**
 * Replaces the contents of a single page element with a randomquote_link()
 * and periodically refreshes it with a new quote.
 *
 * @param string $element
 *   The jquery selector for a DOM page element whose contents will be replaced.
 *
 * @param int $delay
 *   The number of milliseconds to wait between subsequent refreshes of the quote.
 *
 * @param boolean $immediate
 *   Whether to insert the first randomquote immediately, with no delay.
 *
 * Example usage (in MYTHEME/template.php):
 *   function MYTHEME_preprocess_page(&$vars) {
 *     // Show a new random quote in the footer every thirty seconds.
 *     randomquote_js('#footer', 30000);
 *   }
 */
function randomquote_rotate_js($element, $delay, $immediate=TRUE) {

For efficiency's sake, randomquote_link() doesn't call any theme functions.
The following code will output a fully-themed random quote:

  echo theme('quotes_quote',array('node' => node_load(randomquote_nid())));
