Callback functions
Sometimes your field type is so unique that you need to provide the display of it yourself. For these fields, the plug-in has a callback. You can tell the plug-in that whenever it displays the field, to first “call back’ to your custom function. For example, suppose, for your “sum” field, you want all positive numbers to display one way, and all negative numbers to display another way.
First, set up the callback. You give the callback the name of the field and the name of the function that handles that field:
<? $db->setFieldCallback('sum', 'sumDisplay'); ?>
Then, set up the function. The function will receive the field’s value, the context (‘display’ or ‘form’), the row that the field is a part of, the field’s name, and the field’s info.
<? function sumDisplay($value, $context) { if ($context == 'display') { if ($value < 0) { $class = 'debit'; } else { $class = 'credit'; } $value = '<span class="' . $class . '">' . $value . '</span>'; } return $value; } ?>
Often, as above, you won’t care about the row, the field’s name or the field’s info. The row is an array that contains each column in the row, using the column name as the key. The field’s info is an array that currently contains the following information:
| type | the field’s MySQL type |
|---|---|
| size | the field’s MySQL size, if it has any |
| choices | the field’s MySQL enum choices, if it has any |
| callback | the field’s callback function, if you have specified one |
| format | the field’s format, if you have specified one |
| localtype | the special field type if you have specified one |
| sort | the field’s sort equivalent, if you have specified one |
| title | the column title if you have specified one |
Currently, the context is always “display”. Callbacks don’t yet occur for “form”. Expect that to change without warning, so always check the context.
Full row callback
If you want full control over each row, you can set a callback for the entire row. Before the row is displayed, it will call your callback function and you can modify it however you wish.
<? $db->setCallback('fixRow'); ?>
Your function will receive four values:
- The row: an array of field names and field values, of each item in the row.
- A true or false depending on whether this is a list display or an individual item.
- A true or false depending on whether this is a display or a form.
- A true or false depending on whether or not the table’s header row has been displayed yet.
If you “unset()” items from a row, they won’t be displayed—they won’t even get a column. If you change values in the row, the new values will be displayed.
Pre-display callback
If you need to display something from the data, or from the first row of data, before the plug-in beings to display it, you can set a callback function for that as well. The function requirements are the same as for setCallBack().
<? $db->setPreCallback('showThumbnail'); ?>