GeeklogWiki - User contributions [en]

Dynamic Blocks

2005-11-22T00:34:29Z

Trinity:

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 alows plugin
developers to create left and right blocks in Geeklog on the fly without adding a block to the blocks table.
This is acomplished by inserting the block data directly into the aray 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..

<h3>Dynamic Block API</h3>

This section will describe and document how to enable your plugin to use the Geeklog dynamic block API.
This will be a usefull 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 straight forward 

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 avaliable in Geeklog 1.4 and is not present in previous versions of Geeklog.

There is only one plugin function that is requiered 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:

<div align="center">
<table cellPadding="2" width="100%" border="1"
style="border-collapse: collapse" bordercolor="#111111"
cellspacing="0">
<tr>
<th vAlign="top" width="4%"> </th>
<th vAlign="top" width="31%">Function</th>
<th vAlign="top" width="95%">Description of Function</th>

</tr>
<tr>
<td class="codeheader" vAlign="top" width="5%" align="center">1</td>
<td class="codeheader" vAlign="top" width="10%">plugin_getBlocks_<plugin name></td>
<td class="code" vAlign="top" width="85%">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 veiw any blocks that are returned
. It should return an aray of block data containing the dynamicaly generated blocks
that you wish the user to see.</td>
</tr>

</table>
</div>

<h3>Function Details and Examples</h3>

Examples provided here have been provided from an initial example created by the
developer of the Dynamic Block API for a plugin curently 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 veiw any blocks that are returned
. It should return an aray of block data containing the dynamicaly generated blocks
that you wish the user to see.

<div style="white-space:pre; border: solid; border-color: black;
border-width: 1; background-color: #DDDDDD; padding: 6px 6px 6px 6px;
font-size: x-small">
/**
* 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 avaliable lables 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;
}

</div>

<h3>Function PLG_getBlocks() for refrence</h3>

<div style="white-space:pre; border: solid; border-color: black;
border-width: 1; background-color: #DDDDDD; padding: 6px 6px 6px 6px;
font-size: x-small">

/**
* 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;
}

</div>

[[Geeklog_1.3x_Documentation|Main TOC]] 
[[Complete TOC]]

Dynamic Blocks

2005-11-22T00:33:22Z

Trinity:

Misc Plugin API's that dont fit any where else

2005-11-22T00:28:58Z

Trinity:

Severial API's have been added to make wrteing plugins easier. these API's dont fit into any spcific catagory

*[[Dynamic Blocks]]

[[Geeklog_1.3x_Documentation|Main TOC]] 
[[Complete TOC]]

Misc Plugin API's that dont fit any where else

2005-11-22T00:26:40Z

Trinity:

Severial API's have been added to make wrteing plugins easier. these API's dont fit into any spcific catagory

*[[Dynamic Blocks]]

Misc Plugin API's that dont fit any where else

2005-11-22T00:25:31Z

Trinity:

Severial API's have been added to make wrteing plugins easier. these API's dont fit into any spcific catagory

[[Dynamic Blocks]]

Programmers/Developers Documentation

2005-11-22T00:21:42Z

Trinity:

#[[IntroDoc|Introduction]]
#[[Installing Geeklog]]
#[[Administration]]
#[[Users Documentation]]
#[[Programmers/Developers Documentation]]
##[[Geeklog Coding Standards]]
##[[Beginner's Guide to Programming]]
##[[Plugin Development]]
##[[Plugin Developers Handbook]]
##[[Plugin API]]
##*[[Extending Site Statistics with your plugin | Statistics]]
##*[[Integrating the Comment Engine | Comments]]
##*[[Using Geeklog's Search Engine | Search]]
##*[[Adding Moderation Capability | Moderation]]
##*[[RSS API]]
##*[[Misc Plugin API's that dont fit any where else | Misc]]
##[[Theme Developers Guide]]
##[[Translations]]
##[[FAQ]]
##[[Database Schema]]
##[[Common Errors and problems]]

[[Geeklog_1.3x_Documentation|Main TOC]] 
[[Complete TOC]]

Programmers/Developers Documentation

2005-11-22T00:20:20Z

Trinity:

#[[IntroDoc|Introduction]]
#[[Installing Geeklog]]
#[[Administration]]
#[[Users Documentation]]
#[[Programmers/Developers Documentation]]
##[[Geeklog Coding Standards]]
##[[Beginner's Guide to Programming]]
##[[Plugin Development]]
##[[Plugin Developers Handbook]]
##[[Plugin API]]
##*[[Extending Site Statistics with your plugin | Statistics]]
##*[[Integrating the Comment Engine | Comments]]
##*[[Using Geeklog's Search Engine | Search]]
##*[[Adding Moderation Capability | Moderation]]
##*[[RSS API]]
##*[[Misc]]
##[[Theme Developers Guide]]
##[[Translations]]
##[[FAQ]]
##[[Database Schema]]
##[[Common Errors and problems]]

[[Geeklog_1.3x_Documentation|Main TOC]] 
[[Complete TOC]]

Geeklog's way of doing things

2005-05-16T03:01:48Z

Trinity:

All of Geeklog's php files are pure php. PHP allows you to use php as a scripting language imbedded in html files but this is not how Geeklog does it. All of Geeklog's php files must have <?php as the first five characters and end with ?>. Failure to structure your Geeklog files this way will cause session and header errors. Geeklog attempts as much as possible to have only php code in the php files. Two of the conventions used in Geeklog to accomplish this are the use of templates and language files.

Time will be well spent by the Geeklog plugin or block developer to become familiar with several Geeklog libraries. The following section outlines the more important or frequently used libraries, functions and standards.

== lib-common.php: ==

The Geeklog plugin or block developer should have a good understanding of lib-common.php which contains most of the display routines as well as some other general purpose routines. All of the Geeklog display routines return html. They do not contain echos or prints themselves. The way the Geeklog system is designed; you usually put your code between Geeklog display routines. For example: code to display a page would look like this:

$display = COM_siteHeader(); 
$display .= COM_startBlock("Title of Your Block"); 
$display .= "Some words"; 
$display .= somefunction(); 
$display .= COM_endBlock; 
$display .= COM_siteFooter(true); 
echo $display;

A summary of commonly used Geeklog functions are described below but reference the attached lib-common.php documentation for further examples.

== lib-security.php: ==

The lib-security.php file contains the interface routines to the security system used in Geeklog. See the attached lib-security.php documentation. There are several SEC type functions that you may want to use in your projects. The table Commonly Used Geeklog Functions at the end of this section defines a couple of the more commonly used functions.

== lib-database.php: ==

All database access should take place through the database abstraction in lib-database.php and table names should be accessed through the $_TABLES array. The table definitions in this array will then include whatever table prefix this site is using. You should ensure that your plugin or block uses the $_TABLES['mytable'] for all Database access related functions.
*Block developers and site admins installing the block need to edit the lib-database.php program and add the new $_TABLES entries for your block tables. Ensure you follow the same standard by using the $_DB_table_prefix.
*Plugin developers need to define their tables in the plugin config.php file. You have the ability to use the $_TABLES array or use your own plugin specific array to maintain the table definitions. It's recommend that your arrays use a name such as _XX_TABLES, where XX are two letters to describe your plugin. Once the plugin is installed and enabled, the tables defined in the config.php for the plugin are automatically known as globals.

== lib-plugins.php: ==

This library contains all the code used to interface your plugin or block to Geeklog. You will not call any code from here directly. The functions in this file are called by the Geeklog main programs as they are used to call all plugins and are used to resolve the plugin name and check if your plugin has a particular function. You will usually only have to look at this file to understand some nuance of the implementation. See the documentation for functions.inc and the original plugin documentation for further help.

== How your Plug-in or Block Interacts with Geeklog: ==

The program lib-common.php is the key to all interaction with Geeklog. It includes Geeklog's config.php and the rest of the Geeklog code libraries.
*At the top of lib-common.php is an include of lib-custom.php. This is where you place all your block functions. They are then included when the site index.php is called.
*At the very end of lib-common.php is a check for all enabled plugins. A plugin is registered with Geeklog when it has a record in the plugins table and the field pi_enabled is true. For all registered and enabled plugins, the code in lib-common.php will include the functions.inc file for each plugin. This is why the naming convention and location for each plugin file is strictly defined. All code libraries or configuration files your plugin needs should be included in your functions.inc. Since the plugins config.php is now also included this way - via the include in functions.inc - the variables in your plugin config.php become global and can be referenced in your plugin functions.

== Common Global Variables ==

There are a few commonly used globals within Geeklog that you will want to use and reference. The following table outlines the more frequently used ones and its recommended that these be used instead of hard coding paths and table names in your links or project code.

<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="75%" id="AutoNumber2" height="72">
<tr>
<td width="27%" bgcolor="#000000" height="16">
 Variable</td>
<td width="73%" bgcolor="#000000" height="16">
  Description</td>
</tr>
<tr>
<td width="27%" height="17">$_CONF['path_html']</td>
<td width="73%" height="17">Fully qualified path to your
sites public_htmk path</td>
</tr>
<tr>
<td width="27%" height="18">$_CONF['site_url']</td>
<td width="73%" height="18">Full URL to your sites
public_html directory</td>
</tr>
<tr>
<td width="27%" height="18">$_CONF['site_admin_url']</td>
<td width="73%" height="18">Full URL to your sites admin
directory</td>
</tr>
<tr>
<td width="27%" height="18">$_USER['uid']</td>
<td width="73%" height="18">Current user ID. A uid of 1 is an
anonymous user</td>
</tr>
<tr>
<td width="27%" height="18">$_TABLES['tablename']</td>
<td width="73%" height="18">A array of geeklog tables with
the site prefix defined.</td>
</tr>
</table>

== Commonly used Geeklog functions ==

The following is a list of commonly used Geeklog functions that as developers we use and recommend you become more familiar with and use in your development projects. You will find example usage of these functions throughout the Geeklog code.

<table border="1" style="border-collapse: collapse" bordercolor="#111111" width="100%" id="AutoNumber1" height="197" cellpadding="3" cellspacing="0">
<tr>
<td width="13%" bgcolor="#000000" height="18">
 Function Name</td>
<td width="73%" bgcolor="#000000" height="18">
   Description</td>
</tr>
<tr>
<td width="13%" height="16">
 COM_siteHeader</td>
<td width="73%" height="16">Display the main site header and
optionally if 'none' is passed do not display the left blocks</td>
</tr>
<tr>
<td width="13%" height="16">
 COM_siteFooter</td>
<td width="73%" height="16">Display the main site footer and
optionally if 'true' is passed display the right blocks</td>
</tr>
<tr>
<td width="13%" height="32">
 COM_startBlock</td>
<td width="73%" height="32">Formats the block title using the
selected theme - pass the title, helpfile if any and optional block theme to
apply if you do not want to use default</td>
</tr>
<tr>
<td width="13%" height="16">
 COM_endBlock</td>
<td width="73%" height="16">Formats the block footer using
the selected theme or the optional block theme if you do not want to use
default</td>
</tr>
<tr>
<td width="13%" height="12"> COM_errorLOG</td>
<td width="73%" height="12">Use to format an error message or
use for debugging - view output in <geeklog_dir>/logs/error.log</td>
</tr>
<tr>
<td width="13%" height="14">
 DB_query</td>
<td width="73%" height="14">Execute a formatted SQL query and
return the record set to an array of records (which is also an array)</td>
</tr>
<tr>
<td width="13%" height="16">
 DB_fetchArray</td>
<td width="73%" height="16">Retrieve a record as an array
from the returned record set - which DB_query returned.</td>
</tr>
<tr>
<td width="13%" height="16">
 DB_numROWS</td>
<td width="73%" height="16">Returns the number of records
retrieved by the DB_query result</td>
</tr>
<tr>
<td width="13%" height="16"> DB_getItem</td>
<td width="73%" height="16">Retrieve one record as an array.
Pass a formatted SQL stmt with WHERE clause to retrieve one record</td>
</tr>
<tr>
<td width="13%" height="15"> COM_checkHTML</td>
<td width="73%" height="15">Use to strip out $, <, > , [code]
and replace with the HTML codes</td>
</tr>
<tr>
<td width="13%" height="15"> COM_checkWords</td>
<td width="73%" height="15">Use to check passed text for any
HTML tags that are not allowed as per the site config.php setting</td>
</tr>
<tr>
<td width="13%" height="15"> SEC_inGroup</td>
<td width="73%" height="15">Used to check if user has passed
group rights. Example: SEC_inGroup('Root') - returns true if user is</td>
</tr>
<tr>
<td width="13%" height="15"> SEC_hasRights</td>
<td width="73%" height="15">Used to check if user has access
right (feature). Example: SEC_hasRights('myplugin.edit')</td>
</tr>
</table>

[[Category:Plugin_Developers_Handbook]]