Conventions used in this document:

• Any text that is in this font is considered code, a literal value, or the name of a file, folder, MySQL table, MySQL field, or a value in a MySQL field.
• Any text that is surrounded by angle brackets like  <this>  means that you should substitute it for your own value.
  Example: vconsole/modules/<module>/ means that you should substitute <module> for your own value like invoices for the Manage Invoices module.
• Any text that is surrounded by square brackets like  [this]  means that it is optional.
  Example: check_email($email, $error[, $dnscheck]);  means that [, $dnscheck] is optional
• When you see ... in the code font, this means that you can add 1 or more items at that point. Do not actually include ... in your code.
  

Introduction.
This section is targeted to advanced VConsole developers. Some the the techniques used here are difficult at best to understand and implement. However, we do our best to give a detailed explanation on each technique here.

Specifying AJAX based action functions in your functions.php file.
This technique applies to any datamanager type module.
Prerequisite Reading: The Datamanager.

You can specify an AJAX based action function in your functions.php file for any <formathelp> named function. What this does is when the user hovers over a field, it will display a message to the user to wait and it will call a datamanager action file via AJAX. The output of that action will be displayed in your hover help box. If used, your action file in the vconsole/modules/<module>/actions/ folder MUST output the HTML code that you want to show as help and then exit. It MUST NOT return or you will get the entire data manager interface in your help box. OK, so here is how to do it.

1. Define your function in the functions.php file.
   function invoiceitems_format_help($record) {
     return "ajax(\"Please wait.\", \"action=getitems&item_{$record['id']}=1\");";
   }
   
   OK, so let's look this over. What's required is that you return a string that is evaluated by javascript. The string MUST start with ajax(\" in order to be evaluated. The ajax function takes 2 arguments. The first is a message to display to the user while the ajax executes and the 2nd argument must be a url encoded string that contains an action parameter and what ever other parameters you want to pass to your action file. You probably want to pass the record id back in so that your action file knows what record the user is currently hovering over. In the example, we set the parameter item_<id>=1. This is because the PHP function datamanager_getselected() understands this and will return an array with a single element which is whatever <id> is set to.
    
2. Now, you must define a dms field that has the <formathelp> parameter set to the name of the function. See the green text below. (We only show part of the data structure below because we assume that you have already read the prerequisite reading.)
   
   'invoiceitems' => array(
     'header' => array(
       'type' => 'text',
       'title' => 'Invoice Items',
     ),
     'data' => array(
       'type' => 'text',
       'formathelp' => 'invoiceitems_format_help'
     )
   )
   
    
3. Finally, you must create an action file in the vconsole/modules/<module>/actions/ folder that gets the parameters that you pass back in using your eval'd ajax code as displayed above in your function. This action file should read the passed in parameters, get the data that you want it get, output that data as HTML, and exit. Here is a quick example that corresponds to the examples above. A table called invoice_items is queried and all items that are assigned to the invoice that is being hovered over are printed out and then the action exits. There is also some simple error checking in this script. Since the action parameter that is passed in is getitems, this file should be named getitems.php
   <?php
   global $OUT, $GLOB, $DATA, $PARAMS;
   
   // Get the record that is being hovered over.
   $selected = datamanager_getselected();
   $id = $selected[0];
   // If no record, output an error message.
   if (!$id) {
     set_message('error', 'Invalid record');
     print $OUT['messages'];
     exit;
   }
   // Get the invoice items
   $out = '';
   db_query("SELECT * FROM `invoice_items`
     WHERE `invoice_id` = " . db_quote($id), $dbr);
   while ($item = mysql_fetch_assoc($dbr)) {
     $out .= "{$item['title']} - {$item['price']}<br>\n";
   }
   // If no items, set a message
   if (!$out) {
     set_message('warn', 'No invoice items found.');
     print $OUT['messages'];
     exit;
   }
   // Print the invoice items
   print $out;
   exit;
   ?>
   

Do You Have An Advanced Question Or How To?
Post it as a comment below and we may feature it as part of the native text on this page and we will give you credit along with a link to your website.