Dynamic Blocks
Contents
Dynamic Block Plugin API in Geeklog 1.4
The dynamic block plugin API is a new feature of Geeklog 1.4. This new API function allows plugin developers to create left and right blocks in Geeklog on the fly without adding a block to the blocks table. This is accomplished by inserting the block data directly into the array of blocks that is created from a SQL call to the blocks table before it is used to create what is displayed. What follows is an description of the API call and its use in a plugin.
Dynamic Block API
This section will describe and document how to enable your plugin to use the Geeklog dynamic block API. This will be a useful feature of plugin functionality for many developers and it has been designed to be easy to integrate into your plugin. We have done our best to make this straightforward.
NOTE: You will need to be using Geeklog version 1.4 or later to successfully use the Dynamic Block API. This plugin API is only available in Geeklog 1.4 and is not present in previous versions of Geeklog.
There is only one plugin function that is required to support dynamic blocks in a plugin. The example function that is included in this explanation are very complete. You should only need to edit them for your plugin name name. The following table summarizes the functions:
| Function | Description of Function | |
|---|---|---|
| 1 | plugin_getBlocks_<plugin name> | This function expects two parameters: side and topic. This function is called when a left and right blocks are created with COM_showBlocks in lib-common.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to view any blocks that are returned. It should return an array of block data containing the dynamically generated blocks that you wish the user to see. |
As of Geeklog 2.0.0 there is one additional plugin function that can be used. It is not required to support dynamic blocks in a plugin. The plugin function allows the configuration options to be displayed in the Admin Block Editor to make it easier for Admins to see all blocks that can be displayed on the site. If Admins wish to edit the configuration of these dynamic blocks they do so in the Geeklog Configuration (if the plugin supports this). The following table summarizes the functions:
| Function | Description of Function | |
|---|---|---|
| 1 | plugin_getBlocksConfig_<plugin name> | This function expects two parameters: side and topic. This function is called by the Admin Block Editor. |
Function Details and Examples
Examples provided here have been provided from an initial example created by the developer of the Dynamic Block API for a plugin currently in development
This function expects two parameters: side and topic. This function is called when a left and right blocks are created with COM_showBlocks in lib-common.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to view any blocks that are returned. It should return an array of block data containing the dynamically generated blocks that you wish the user to see.
/**
* Returns blocks for this plugin that should appear when COM_showBlocks is run
*
* NOTE: this MUST return the label/value pairs in the following format
* $items[] = array('label1' => 'value', 'label2' => 'value')
* Basic available labels are..
* name Name of block (BLOCK_ID)
* type Must always be set 'dynamic' unless you use advanced API labels
* Advanced API means you set all fields that COM_showBlocks
* expects to see from the blocks table. All labels are column names
* title Title of block
* blockorder Block order number
* content Body of the block (the html output)
* help Optional url to a help page
*
* You must only return left or right blocks based on $side and
* you must also do your own security checks. Everything you send
* will show up on a page load
*
*
*
*/
function plugin_getBlocks_glcommerce($side, $topic='' )
{
global $_CONF, $_USER, $HTTP_SERVER_VARS, $REQUEST_URI, $sess, $db;
// only show on a page in the plugin's dir
If (in_string('glcommerce', $REQUEST_URI))
{
// generate left blocks
if ($side=='left')
{
$display1 = glc_makemenu();
$display2 = glc_latestprod();
$items[] = array('name' => 'glcommerce_1',
'type' => 'dynamic',
'onleft' => 1,
'title' => 'Shop Menu',
'blockorder' => 1,
'content' => $display1,
'help' => '/glcommerce/help.html');
$items[] = array('name' => 'glcommerce_2',
'type' => 'dynamic',
'onleft' => 1,
'title' => 'Latest Products ',
'blockorder' => 1,
'content' => $display2,
'help' => '/glcommerce/help.html');
} else {
// else generate right blocks
$display3 = glc_featuredprod()'
$display4 = glc_minicart();
$items[] = array('name' => 'glcommerce_3',
'type' => 'dynamic',
'onleft' => 0,
'title' => 'Featured Stuff',
'blockorder' => 1,
'content' => $display3,
'help' => '/glcommerce/help.html');
$items[] = array('name' => 'glcommerce_4',
'type' => 'dynamic',
'onleft' => 0,
'title' => 'My Cart',
'blockorder' => 1,
'content' => $display4,
'help' => '/glcommerce/help.html');
}
}
return $items;
}
Function PLG_getBlocks() for reference
/**
* gets Geeklog blocks from plugin's
*
* Returns data for blocks on a given side and, potentially, for
* a given topic.
*
* @param string $side Side to get blocks for (right or left for now)
* @param string $topic Only get blocks for this topic
* @return array of block data
*
*/
function PLG_getBlocks( $side, $topic='')
{
global $_PLUGINS;
$ret = array();
foreach ($_PLUGINS as $pi_name)
{
$function = 'plugin_getBlocks_' . $pi_name;
if (function_exists($function))
{
$items = $function($side, $topic='');
if (is_array ($items))
{
$ret = array_merge ($ret, $items);
}
}
}
// future code to do a lib-custom function
/*
if (function_exists('CUSTOM_getBlocks')) {
$cust_items .= CUSTOM_getBlocks($side, $topic='');
if (is_array ($cust_items)) {
$ret = array_merge ($ret, $cust_items)
}
}
*/
return $ret;
}
