modules/active_template/template_api.module

<?php
// $Id$
// by Collective Colors - http://collectivecolors.com

/*******************************************************************************
 * Template API
 * 
 * The template api module provides a framework that allows for the management, 
 * evaluation, and rendering of templates. 
 */

//------------------------------------------------------------------------------
// Template API constants (just in case we change the names later)

/**
 * Prefix these constants with ([T]emplate [A]pplication [P]rograming 
 * [I]nterface) so that constants have a much smaller chance of conflicting 
 * with constants defined in the Drupal core and other Drupal modules.
 * 
 * It's situations like this that truly makes me appreciate object oriented 
 * programming and encapsulation of class variables and constants.
 */
define("TAPI_XID_DEFAULT", 0);

define("TAPI_TYPE_DEFAULT",  'default');
define("TAPI_TYPE_TEMPLATE", 'tpid');

define('TAPI_FORMAT_ARRAY', 0);
define('TAPI_FORMAT_ASSOC', 1);
define('TAPI_FORMAT_TREE',  2);

define("TAPI_OP_CREATE",     0);
define("TAPI_OP_EDIT",       1);
define("TAPI_OP_ACTIVATE",   2);
define("TAPI_OP_DEACTIVATE", 3);
define("TAPI_OP_DELETE",     4);

//------------------------------------------------------------------------------
// Template API globals (equivalent to class variables for template functions)

$tapi_templates = array();

//------------------------------------------------------------------------------
// Drupal hooks
//------------------------------------------------------------------------------

/*******************************************************************************
 * Implementation of hook_help
 */
function template_api_help($section) {
  if ($section == 'admin/help#template_api') {
    $output = "<p>The template api module provides a framework that allows for "
            . "the management, evaluation, and rendering of templates.</p>";
  }
  return $output;
}

//------------------------------------------------------------------------------
// Template API
//
// This API does not handle user permissions.  That responsibility is left to 
// the modules that utilize this module.
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// Template Management

/*******************************************************************************
 * Retrieve templates
 *
 * This function caches templates that are fetched from the database which 
 * allows us to use this function to return formatted data objects with 
 * specified templates.  If no ids are passed to this function the caching 
 * mechanism is bypassed and it acts like a refresh of the cache for the 
 * template type specified.
 *
 * @param mixed $ids - either an id number or an array of id numbers
 * @param string $type - denotes the type of id number
 * @param boolean $active - whether or not we want only active templates 
 *                          returned
 * @param int $format - output format (FORMAT_ARRAY | FORMAT_ASSOC | 
 *                                     FORMAT_TREE)
 * @return array if format == FORMAT_TREE  -> assoc[$type][$xid][] = $template
 *               if format == FORMAT_ASSOC -> assoc[$tpid] = $template
 *               if format == FORMAT_ARRAY -> array[] = $template
 */
function template_api_get_templates($ids    = array(), 
                                    $type   = TAPI_TYPE_TEMPLATE, 
                                    $active = TRUE,
                                    $format = TAPI_FORMAT_ARRAY) {
  global $tapi_templates;
  
  // Allow for single id input.
  if (is_numeric($ids)) {
		$ids = array($ids);
	}
	
	// Find all templates that have not already been loaded into memory.
	$new_ids = template_api_find_new_templates($ids, $type);
	
	// We only want to query templates if no ids given or if there are uncached 
	// templates found.
	if (!_valid_ids($ids) || count($new_ids)) {
	  $types_loaded = array();
	  $result       = template_api_query_templates($new_ids, $type, $active);
	  
    while ($template = db_fetch_object($result)) {
    
      // Load all external template data such as associated files and give 
      // external modules a chance to alter the template before it is added to 
      // the globally loaded templates.
      template_api_load_template($template);

      // Assign the same template to multiple tree branches so we can find it 
      // with different parameter sets and avoid extra database queries.  	
  	  $tapi_templates[TAPI_TYPE_TEMPLATE][$template->tpid] = $template;
  	  $tapi_templates[$template->type][$template->xid][]   = $template;
  	  $types_loaded[$template->type][$template->xid]       = 1; 	
    }
    // Make sure templates from external types loaded are sorted by weight.
    // Since different templates are loaded at different times we can not be 
    // sure that the templates are loaded in the proper order.  By sorting
    // directly after the query we can eliminate some extra sorting if we want 
    // to format an existing template multiple ways during execution.
    foreach ($types_loaded as $type_loaded => $type_xids) {
      foreach (array_keys($type_xids) as $type_xid) {
        usort($tapi_templates[$type_loaded][$type_xid], 
              'template_api_compare_templates');
      }
    }
	}
	
	// We can format the output of the query in different ways which are useful 
	// for different purposes.
  return template_api_format_templates($ids, $type, $active, $format); 
}
		
/*******************************************************************************
 * Retrieve a single template
 * 
 * This function has the same basic features as the multi template version.  It
 * just returns the most negatively weighted template of the specified type if 
 * no id is given or if the id is not a template id (tpid).  If just a template 
 * id is given, it returns the specified template.
 *
 * @param int $id - template id number (tpid) or external id number (xid)
 * @param string $type - denotes the type of id number
 * @param boolean $active - whether or not we want only active templates 
 *                          returned
 * @return class - template object
 */
function template_api_get_template($id, 
                                   $type   = TAPI_TYPE_TEMPLATE, 
                                   $active = TRUE) {
  
  $templates = template_api_get_templates($id, $type, $active, 
                                          TAPI_FORMAT_ARRAY);
  if (count($templates)) {
    return $templates[0];
  }  
  return NULL;
}

/*******************************************************************************
 * Return a new default template
 *
 * @param int $xid - external id number
 * @param string $type - denotes the type of id number
 * @return class - default template object
 */
function template_api_get_default_template($xid, $type = TAPI_TYPE_DEFAULT) {

  $template = new stdClass();
	
	$template->tpid = NULL;
	$template->type = $type;
	$template->xid  = $xid;
	
  $template->name        = '';
	$template->description = '';
	$template->active      = 0;
	$template->weight      = 0;
	
	$template->js  = '';
	$template->css = '';
	$template->php = '';

	// Give external modules a chance to initialize the default template before 
	// it is returned.
	template_api_load_template($template, TRUE);
	
	return $template;	
}

/*******************************************************************************
 * Make any last minute additions to the template before it is ready to be used 
 * to display nodes
 *
 * This function is meant for internal use only!  If you need to load a template
 * call template_api_get_templates(...), template_api_get_template(...), or
 * template_api_get_default_template(...).
 *
 * @param class $template - base template object
 * @param boolean $initialize - whether or not this template is newly created
 * @return class - fully built template object
 */
function template_api_load_template(&$template, $default = FALSE) {
  
  // Let external modules add to the template object as it is loaded.  The 
  // template is passed by reference to allow other modules to edit or remove 
  // template fields and it provides a slight performance boost. Yay!
  foreach (module_implements('load_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_load_template';
      $function($template, $default);
    }
  }  
  return $template;
}

/*******************************************************************************
 * Find any id numbers of the specified type that are not yet loaded into memory
 *
 * @param array $ids - an array of id numbers
 * @param string $type - denotes the type of id number
 * @return array - array of new id numbers
 */
function template_api_find_new_templates($ids, $type = TAPI_TYPE_TEMPLATE) {
  
  global $tapi_templates;
  
  // Load all specified templates if no ids given or templates for type do not 
  // exist yet.
  if (!_valid_ids($ids) || is_null($tapi_templates[$type])) {
    return $ids;
  }
  // Check that all specified templates exist.
  $new_ids = array();
    
  foreach ($ids as $id) {
    if (is_null($tapi_templates[$type][$id])) {
      $new_ids[] = $id;
    }    
  }
  return $new_ids;
}

/*******************************************************************************
 * Return specified templates in different data formats
 *
 * This function is meant for internal use only!  If you want to return 
 * formatted output for templates, call template_api_get_templates(...) or
 * template_api_get_template(...) because these functions will load a template
 * if it is not yet loaded into memory.  This function will NOT load new 
 * templates into memory so any template ids given must already be loaded. 
 *
 * @param array $ids - an array of id numbers
 * @param string $type - denotes the type of id number
 * @param boolean $active - whether or not we want only active templates 
 *                          returned
 * @param int $format - output format (FORMAT_ARRAY | FORMAT_ASSOC | 
 *                                     FORMAT_TREE)
 * @return array if format == FORMAT_TREE  -> assoc[$type][$xid][] = $template
 *               if format == FORMAT_ASSOC -> assoc[$tpid] = $template
 *               if format == FORMAT_ARRAY -> array[] = $template
 */
function template_api_format_templates($ids, 
                                       $type   = TAPI_TYPE_TEMPLATE,
                                       $active = TRUE, 
                                       $format = TAPI_FORMAT_ARRAY) {
  global $tapi_templates;
  
  $output = array();
  
  // If no ids are given then we load all the existing ids from the specified
  // type
  if (!_valid_ids($ids)) {
    $ids = (is_array($tapi_templates[$type]) 
            ? array_keys($tapi_templates[$type]) 
            : array());
  }
    
  foreach ($ids as $id) {
    $id_templates = $tapi_templates[$type][$id];
    
    // Continue to next id if template does not exist or convert template to an 
    // array if there is only one template.  This is the case when the specified
    // id is of type TYPE_TEMPLATE (tpid).  If any other type is given then the 
    // id may contain multiple templates to traverse.  We standardize the value 
    // so we can easily traverse over the id templates in both cases.
    if (!$id_templates) {
      continue;
    }
    elseif(is_object($id_templates)) {
      $id_templates = array($id_templates);
    }
    
    foreach ($id_templates as $template) {
      // Make sure that only the active templates are returned if the active 
      // flag is set to TRUE.
      if ($active && !$template->active) {
        continue;
      }
      // Template is good. Output it in the desired format.
      switch ($format) {
  	    case TAPI_FORMAT_TREE:
  	      $output[$template->type][$template->xid][] = $template;
  	      break;
  	    
  	    case TAPI_FORMAT_ASSOC:
  	      $output[$template->tpid] = $template;
  	      break;
  	    
  	    default:
          $output[] = $template; 
      }
    }    
  }  
  return $output;  
}

/*******************************************************************************
 * Return a database query resource for specified ids of type.  If no ids are 
 * given then all templates are returned.
 *
 * This function is meant for internal use only!  If you want to query templates
 * it is best to use template_api_get_templates(...) or 
 * template_api_get_template(...).  This function does not cache results and
 * it does not add results to the global templates variable, which can cause
 * redundant queries.
 *
 * @param array $ids - an array of id numbers
 * @param string $type - denotes the type of id number
 * @param boolean $active - whether or not we want only active templates 
 *                          returned
 * @return class - template query resource
 */
function template_api_query_templates($ids    = array(), 
                                      $type   = TAPI_TYPE_TEMPLATE, 
                                      $active = TRUE) {
  
  // Query all templates of type if no ids given.
  if (!_valid_ids($ids)) {
    return template_api_query_all_templates($type, $active);
  }
  
  // Format query for execution.
  $field        = ($type == TAPI_TYPE_TEMPLATE ? 't.tpid' : 't.xid');
  $placeholders = implode(',', array_fill(0, count($ids), '%d'));
  
  $conditions   = ($active ? array('t.active = 1') : array());	
  $conditions[] = "($field IN ($placeholders))";
  if ($type != TAPI_TYPE_TEMPLATE) {
    $conditions[] = "t.type = '%s'";
  }
  	
  $query = "SELECT * FROM {template} t " 
         . (count($conditions) ? 'WHERE ' . implode(' AND ', $conditions) : '')
         . " ORDER BY t.tpid, t.weight ";
  
  // Execute query and return database result resource.
  return db_query($query, array_merge($ids, array ($type)));  
}

/*******************************************************************************
 * Return a database query resource for all ids of a specified type.
 *
 * This function is meant for internal use only!  If you want to query templates
 * it is best to use template_api_get_templates(...) or 
 * template_api_get_template(...).  This function does not cache results and
 * it does not add results to the global templates variable, which can cause
 * redundant queries.
 *
 * @param string $type - template type
 * @param boolean $active - whether or not we want only active templates 
 *                          returned
 * @return class - template query resource
 */
function template_api_query_all_templates($type   = TAPI_TYPE_TEMPLATE, 
                                          $active = TRUE) {
  
  // Format query for execution.
  $conditions = ($active ? array('t.active = 1') : array());
	
  if ($type != TAPI_TYPE_TEMPLATE) {
   	$conditions[] = "t.type = '%s'";	
  }
  
  $query = "SELECT * FROM {template} t " 
         . (count($conditions) ? 'WHERE ' . implode(' AND ', $conditions) : '')
         . " ORDER BY t.tpid, t.weight";
  
  // Execute query and return database result resource.
  return db_query($query, $type);
}

/*******************************************************************************
 * Insert a new template into the database
 *
 * If this function is given an existing template as its input then we assign
 * the existing template a new template id before we save it to the database.  
 * This allows us to create a copy of an existing template without overwriting
 * the original.  If an existing template is passed in then the template object
 * will be modified to reflect the new template object that was just created.
 *
 * @param class $template - template object
 * @return boolean
 */
function template_api_create_template(&$template) {
  
  $path = drupal_get_path('module', 'template_api');
  require_once("$path/template_file.inc");
	
	// We go ahead and assign the modified values back to the template itself
	// so that we can continue using this template object in the calling code
	// without worrying about divergent data.
  $template->tpid = db_next_id("{template}_tpid");
	
	$template->name        = check_plain(trim($template->name));
	$template->description = check_plain(trim($template->description));
	
	// These don't need to have the markup checked because the css and js text
	// is meant to be injected into the page and is not displayed on the screen.
	// We don't check the php because it is meant to be executed anyway.
	$template->css = trim($template->css);
	$template->js  = trim($template->js);
	$template->php = trim($template->php);

	// Insert the new template.
	$result = db_query("INSERT INTO {template} " 
	                   . "(tpid, xid, type, "
	                   . " name, description, "
	                   . " css, js, php, "
	                   . " active, weight) " 
										 . " VALUES (%d, %d, '%s', "
										 . "'%s', '%s', '%s', '%s', '%s', %d, %d)", 
													
										$template->tpid,
										$template->xid,
										$template->type,
										$template->name,
										$template->description,
										$template->css,
										$template->js,
										$template->php,
										$template->active,
										$template->weight);
	if (!$result) {
		return template_api_log_status('Template database insert failed.', 
		                               WATCHDOG_ERROR);	
	}
	// Save template files to the file system.	
	if (!template_api_save_template_files($template->tpid, 
	                                      $template->css, 
	                                      $template->js)) {
	  return template_api_log_status('Template file creation failed.', 
		                               WATCHDOG_ERROR);		                                         
  }
  
  // Let external modules insert template object fields
  foreach (module_implements('edit_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_edit_template';
      $function($template, TAPI_OP_CREATE);
    }
  }
	return template_api_log_status('Template creation completed.');
}

/*******************************************************************************
 * Update an existing template in the database
 *
 * @param class $template - template object
 * @return boolean
 */
function template_api_save_template (&$template) {
  
  $path = drupal_get_path('module', 'template_api');
  require_once("$path/template_file.inc");
  
  // We go ahead and assign the modified values back to the template itself
	// so that we can continue using this template object in the calling code
	// without worrying about divergent data.
	$template->name        = check_plain(trim($template->name));
	$template->description = check_plain(trim($template->description));
	
	// These don't need to have the markup checked because the css and js text
	// is meant to be injected into the page and is not displayed on the screen.
	// We don't check the php because it is meant to be executed anyway.
	$template->css = trim($template->css);
	$template->js  = trim($template->js);
	$template->php = trim($template->php);

	// Update the existing template.
	$result = db_query("UPDATE {template} SET"
	                   . " xid = %d,"
	                   . " type = '%s',"		 
	                   . " name = '%s',"
					 					 . " description = '%s',"
										 . " css = '%s',"										
										 . " js = '%s'," 						  
										 . " php = '%s',"
								  	 . " active = %d,"
										 . " weight = %d"  
										 . " WHERE tpid = %d", 

										$template->xid,
										$template->type,									
										$template->name,
										$template->description,
										$template->css,										
										$template->js,
										$template->php,
										$template->active,
										$template->weight,
										$template->tpid);
	if (!$result) {
		return template_api_log_status('Template database update failed.', 
		                               WATCHDOG_ERROR);	
	}
	// Save template files to the file system.	
	if (!template_api_save_template_files($template->tpid, 
	                                      $template->css, 
	                                      $template->js)) {
	  return template_api_log_status('Template file save failed.', 
		                               WATCHDOG_ERROR);		                                         
  }
		
  // Let external modules update template object fields
  foreach (module_implements('edit_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_edit_template';
      $function($template, TAPI_OP_EDIT);
    }
  }
	return template_api_log_status('Template save completed.');
}

/*******************************************************************************
 * Activate a specified template
 *
 * @param class $template - template object
 * @return boolean
 */
function template_api_activate_template(&$template) {
  
  $result = db_query("UPDATE {template} t SET t.active = 1 WHERE t.tpid = %d", 
	                   $template->tpid);
	if (!$result) {	  
	  return template_api_log_status("Template database activation failed.", 
		                                WATCHDOG_ERROR);  
	}
			
  // Let external modules act on template activation.
  foreach (module_implements('edit_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_edit_template';
      $function($template, TAPI_OP_ACTIVATE);
    }
  }
	return template_api_log_status("Template activation completed.");
}

/*******************************************************************************
 * Deactivate a specified template
 *
 * @param class $template - template object
 * @return boolean
 */
function template_api_deactivate_template(&$template) {
  
  $result = db_query("UPDATE {template} t SET t.active = 0 WHERE t.tpid = %d", 
	                   $template->tpid);
	if (!$result) {	  
	  return template_api_log_status("Template database deactivation failed.", 
		                                WATCHDOG_ERROR);  
	}
			
  // Let external modules act on template deactivation.
  foreach (module_implements('edit_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_edit_template';
      $function($template, TAPI_OP_DEACTIVATE);
    }
  } 
	return template_api_log_status("Template deactivation completed.");
}

/*******************************************************************************
 * Delete a specified template
 *
 * @param class $template - template object
 * @return boolean
 */
function template_api_delete_template(&$template) {
  
  $path = drupal_get_path('module', 'template_api');
  require_once("$path/template_file.inc");
	
	$result = db_query("DELETE FROM {template} WHERE tpid = %d", 
	                   $template->tpid);	
	if (!$result) {
	  return template_api_log_status('Template database delete failed.', 
		                               WATCHDOG_ERROR);
	}
	// Delete all template files if they exist.
	if (!template_api_delete_template_files($template->tpid)) {
		return template_api_log_status('Template file delete failed.', 
		                               WATCHDOG_ERROR);
	}
		
  // Let external modules delete template object fields.
  foreach (module_implements('edit_template') as $module) {
    if ($module != 'template_api') {
      $function = $module . '_edit_template';
      $function($template, TAPI_OP_DELETE);
    }
  }  
	return template_api_log_status("Template delete completed.");
}

//------------------------------------------------------------------------------
// Template Evaluation

/*******************************************************************************
 * Render the template for output to the html page and inject necessary template
 * files.
 *
 * If more parameters are passed into the function than just the node object 
 * then the parameters are available via the $params variable.  The first param,
 * $params[0] is set to the given parameter directly after the $nodes parameter.
 *
 * @param string $code - the template code
 * @param array $nodes - an array of nodes to pass to the template code
 * @return string - executed template code
 */
function template_api_render_template(&$template, $nodes) {

  // Inject template css and javascipt files if they exist.
  $path = drupal_get_path('module', 'template_api');
  require_once("$path/template_file.inc");
  
  template_api_inject_files($template->tpid);

  // Evaluate the template code and render html output.
  $output = '';
  if (strlen(trim($template->php))) {
    $params = array_slice(func_get_args(), 2);
    
	  ob_start();
    print eval('?>'. $template->php);
    $output = ob_get_contents();
    ob_end_clean();
  }  
  return $output;
}

/*******************************************************************************
 * Return a fully rendered node ready to be manipulated in a template
 *
 * This function is basically ripped from the node module.  I wish I could just
 * call the node function itself, but the function 'node_view' returns a html
 * rendering instead of the node object and we would not want to manipulate
 * rendered html.  Over abundant use of string replace is BAD, BAD, BAD!!!
 * While I'm on my soap box here; Why in the hell are there two variables
 * for displaying either a teaser or a page on the node functions.  This in my
 * opinion is bad design.  You display one or the other, never both.  So two 
 * variables is freakin redundant.  But aside from these occasional mishaps,
 * Drupal code is pretty clean.  I just wish it was object oriented so you could
 * better encapsulate variables and functions.  Imagine Drupal code without
 * function names that stretch for miles and miles and miles, etc...  I would
 * think that you could achieve the same kind of hook system by implementing
 * interfaces that classes implement and using method relection to dynamically 
 * call interface methods.  Oh well, we can dream can't we.  Oh yeah,
 * one other thing I wish, that Drupal was written in Java instead of PHP.
 * I'll get off my soap box now. 
 *
 * @param int $nid - node id number
 * @param boolean $teaser - whether to render the node teaser or if not true 
 *                          this function will render the node body instead
 * @param boolean $links - whether to render the links appended to the node by 
 *                         other modules
 * @return class - node object
 */
function template_api_prepare_node($nid, 
                                   $teaser = TRUE, 
                                   $links  = TRUE) {
  
  $node = node_build_content(node_load($nid), $teaser, !$teaser);

  if ($links) {
    $node->links = module_invoke_all('link', 'node', $node, $teaser);

    foreach (module_implements('link_alter') AS $module) {
      $function = $module .'_link_alter';
      $function($node, $node->links);
    }
  }

  // Set the proper node part, then unset unused $node part so that a bad
  // theme can not open a security hole.
  $content = drupal_render($node->content);
  if ($teaser) {
    $node->teaser = $content;
    unset($node->body);
  }
  else {
    $node->body = $content;
    unset($node->teaser);
  }

  // Allow modules to modify the fully-built node.
  node_invoke_nodeapi($node, 'alter', $teaser, !$teaser);

  return $node;
}

/*******************************************************************************
 * Render a single node's fields from each node type in the given list of nodes
 *
 * @param array $nodes - array of node objects
 * @param string $target - target HTML field for javascript insert
 * @return string - HTML display of specified node fields with clickable 
 *                  interface
 */
function template_api_get_node_type_variables($nodes, $target) {
	
  $output = '';
  $types  = array();
	
	foreach ($nodes as $node) {
	  if (!array_key_exists($node->type, $types)) {
	    $output .= '<h2>' . t('Example of @type node type', 
	                          array('@type' => $node->type)) 
	               . '</h2>';
			
	    $output .= template_api_get_node_variables($node, $target);
	    
			$types[$node->type] = 1;
	  }
	}
	return $output;
}

/*******************************************************************************
 * Render a single nodes fields and allows for clickable insertion of php code 
 * into target field
 * 
 * This function is basically ripped from the contemplate.module
 * Great function. Great module.
 *
 * @param assoc $assoc - associative array of data fields to recurse through
 * @param string $target - target HTML field for javascript insert
 * @param string $parents - used by recursion
 * @param boolean $object - used by recursion
 * @return string - HTML display of node fields with clickable interface
 */
function template_api_get_node_variables($assoc, $target, 
                                         $parents = FALSE, 
                                         $object  = FALSE) {
  if (is_object($assoc)) {
    $assoc = (array)$assoc;
  }
  if (is_array($assoc)) {
    $output .= "<dl>\n";
    foreach($assoc as $field => $value) {
    	if ($parents) {
        if ($object) {
          $field = $parents . '->'. $field;
        }
        else {
          if (is_int($field)) {
            $field = $parents . '[' . $field . ']';
          }
          else {
            $field = $parents . '[\'' . $field . '\']';
          }
        }
      }

      $type = "";
      if (!is_string($value)) {
        $type = " (" . gettype($value) . ")";
      }

      if (!is_array($value) && !is_object($value)) {
        if ($field == 'title' || (substr($field, -9) == "['value']")) {
          $security = t(" <span style='color:red;font-weight:bold'>**</span>");
          $insert   = "'<?php print check_plain(\$nodes[0]->"
                    . addslashes($field) 
                    . ") ?>'";
        }
        else {
          $security = '';
          $insert   = "'<?php print \$nodes[0]->". addslashes($field) 
                    . " ?>'";
        }

        $output .= "<dt><a href=\"#\" " 
                .  "onclick=\"insertAtCursor(document.getElementById"
                .  "('edit-$target'), $insert);return false;\" " 
                .  "title=\"insert this variable into $target\">"
                .  "\$nodes[0]->$field</a>{$security}{$type}</dt>\n";
      }
      else {
        $output .= "<dt>\$nodes[0]->$field$type</dt>\n";
      }

      $output .= "<dd>\n";
      if (is_array($value)) {
        $output .= template_api_get_node_variables($value, 
                                                   $target, $field);
      }
      elseif (is_object($value)) {
        $output .= template_api_get_node_variables((array)$value, 
                                                   $target, $field, TRUE);
      }
      else {
        $value   = is_bool($value) ? ($value ? 'TRUE' : 'FALSE') : $value;
        $output .= htmlspecialchars(print_r($value, TRUE)) . "\n";
      }
      $output .= "</dd>\n";
    }
    $output .= "</dl>\n";
  }
  return $output;
}

//------------------------------------------------------------------------------
// Auxillary Functions

/*******************************************************************************
 * Log the status of an operation with the system and display a status message
 *
 * @param string $message - message to associate with event
 * @param string $type - event type (WATCHDOG_NOTICE | WATCHDOG_WARNING | 
 *                                   WATCHDOG_ERROR)
 * @return boolean
 */
function template_api_log_status($message, $type = WATCHDOG_NOTICE) {
  
  $ok = TRUE;
  
  // Set session message to be displayed on web page
  switch ($type) {
    case WATCHDOG_NOTICE:
      drupal_set_message(t($message), 'status');
      break;
    case WATCHDOG_WARNING:
    case WATCHDOG_ERROR:
      drupal_set_message(t($message), 'error');
      $ok = FALSE;
      break;
    default:
      return FALSE;
  }
  // Set log message that is stored and can be viewed later
  watchdog("template api", t($message), $type, $_GET['q']);
  
  return $ok;
}

/*******************************************************************************
 * Compare two templates by weight for sort ordering of id templates
 *
 * @param class $t1 - template object
 * @param class $t2 - template object
 * @return int - [  0 ] if templates are same weight
 *               [  1 ] if second template has heavier weight
 *               [ -1 ] if first template has heavier weight
 */
function template_api_compare_templates($t1, $t2) {
  if ($t1->weight == $t2->weight) {
    return 0;
  }
  return ($t1->weight < $t2->weight ? -1 : 1);
}

/*******************************************************************************
 * Validate id number input
 *
 * @param array $ids - an array of id numbers
 * @return boolean
 */
function _valid_ids($ids) {
  return (is_array($ids) && count($ids));
}