Difference between revisions of "Functions.inc - Listing of the Plugin Functions"
From GeeklogWiki
m (Changed category) |
(fixed formatting in tables) |
||
| Line 1: | Line 1: | ||
The following section outlines the Geeklog Plugin API functions which you | The following section outlines the Geeklog Plugin API functions which you | ||
have available to integrate your project or extend your projects features. | have available to integrate your project or extend your projects features. | ||
| − | The only mandatory function is the uninstall function. If any of the functions | + | The only mandatory function is the uninstall function. If any of the functions are not implemented they will be be skipped when Plugin feature is checked from within Geeklog. For example, when building the user menu, all enabled plugins are checked to see if the plugin_getuseroption_pluginname exists. If for plugin <i>mycontacts</i> the plugin_getuseroption_mycontacts() does not exist, it is skipped and the next enabled plugin is checked. |
| − | are not implemented they will be be skipped when Plugin feature is checked from | ||
| − | within Geeklog. | ||
| − | checked to see if the plugin_getuseroption_pluginname exists. If for plugin <i>mycontacts</i> the | ||
| − | plugin_getuseroption_mycontacts() does not exist, it is skipped and the next | ||
| − | enabled plugin is checked. | ||
| − | == Core Plugin Functions | + | == Core Plugin Functions == |
There are several core functions that are normally always implemented for | There are several core functions that are normally always implemented for | ||
| − | plugins. Function prototypes and sample code for all these functions are available in the | + | plugins. Function prototypes and sample code for all these functions are available in the Universal Plugin Kit. If you want to enable any of them just modify the code to fit your plugin and uncomment the code. |
| − | Universal Plugin Kit. If you want to enable any of them just modify the code | ||
| − | to fit your plugin and uncomment the code. | ||
<table border="2" cellspacing="0" cellpadding="3" width="100%"><tr> | <table border="2" cellspacing="0" cellpadding="3" width="100%"><tr> | ||
| Line 35: | Line 28: | ||
| − | + | == Optional Functions == | |
| − | == Optional Functions | ||
| − | |||
The following optional plugin functions are broken out into the following | The following optional plugin functions are broken out into the following | ||
related groupings. The first group are the functions required to support | related groupings. The first group are the functions required to support | ||
| − | moderation within your plugin. If you want your plugin to be moderated like Geeklog stories | + | moderation within your plugin. If you want your plugin to be moderated like Geeklog stories and links then you must implement these functions. |
| − | and links then you must implement these functions. | ||
| − | |||
<table border="2" width="100%" cellpadding="3" cellspacing="0"> | <table border="2" width="100%" cellpadding="3" cellspacing="0"> | ||
| Line 52: | Line 41: | ||
<tr> | <tr> | ||
<td width="288" >plugin_ismoderator_<plugin name></td> | <td width="288" >plugin_ismoderator_<plugin name></td> | ||
| − | <td width="541" >Checks if the current user has rights to moderate for the plugin and returns | + | <td width="541" >Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.</td> |
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td width="288" >plugin_submissioncount_<plugin name></td> | <td width="288" >plugin_submissioncount_<plugin name></td> | ||
| − | <td width="541" >Calculates the current number of submissions awaiting moderation and returns | + | <td width="541" >Calculates the current number of submissions awaiting moderation and returns that number.</td> |
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
| Line 66: | Line 53: | ||
<tr> | <tr> | ||
<td width="288" >plugin_moderationvalues_{plugin name} </td> | <td width="288" >plugin_moderationvalues_{plugin name} </td> | ||
| − | <td width="541" >Returns the primary key column name, the main | + | <td width="541" >Returns the primary key column name, the main table name (called {plugin name}) and the list of fields from that table that you'd like to have show up on the moderation page.</td> |
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
| Line 76: | Line 61: | ||
<tr> | <tr> | ||
<td width="288" >plugin_submit_{plugin name}</td> | <td width="288" >plugin_submit_{plugin name}</td> | ||
| − | <td width="541" >Shows the submission form for your plugin. Returns a string containing the | + | <td width="541" >Shows the submission form for your plugin. Returns a string containing the HTML to display the plugin submission form.</td> |
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td width="288">plugin_moderationapprove_{plugin name}</td> | <td width="288">plugin_moderationapprove_{plugin name}</td> | ||
| − | <td width="541">Takes an ID into {plugin name}submission and moves it to the main table called {plugin name}. | + | <td width="541">Takes an ID into {plugin name}submission and moves it to the main table called {plugin name}. This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.</td> |
| − | |||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td width="288" >plugin_moderationdelete_{plugin name} </td> | <td width="288" >plugin_moderationdelete_{plugin name} </td> | ||
| − | <td width="541" >Takes an ID into {plugin name}submission table and deletes it. | + | <td width="541" >Takes an ID into {plugin name}submission table and deletes it. This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.</td> |
| − | |||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
</table> | </table> | ||
| − | |||
| − | |||
| + | If you want your plugin to retrieve search results when the Geeklog search is used or present your plugin as a possible search type then you will want to implement these functions. | ||
<table border="2" width="100%" cellspacing="0" cellpadding="3"> | <table border="2" width="100%" cellspacing="0" cellpadding="3"> | ||
| Line 108: | Line 83: | ||
<td width="288">plugin_getsearchtypes_{plugin | <td width="288">plugin_getsearchtypes_{plugin | ||
name}</td> | name}</td> | ||
| − | <td width="541">You will probably want to add a | + | <td width="541">You will probably want to add a new type in the Type drop down on search.php. This function prints the option tags needed. Make sure that the value tag is {plugin name}</td> |
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td width="288">plugin_dopluginsearch_{plugin | <td width="288">plugin_dopluginsearch_{plugin | ||
name}</td> | name}</td> | ||
| − | <td width="541">Takes the search criteria and lets | + | <td width="541">Takes the search criteria and lets you build search results for your plugin. This returns a string array of table rows, one row for each record returned by your search.</td> |
| − | |||
| − | |||
</tr> | </tr> | ||
</table> | </table> | ||
| − | |||
If you want your plugin to support comments and use the Geeklog comment | If you want your plugin to support comments and use the Geeklog comment | ||
| − | engine, then you need to implement these functions in your plugin functions.inc | + | engine, then you need to implement these functions in your plugin functions.inc file |
| − | file | ||
<table cellpadding="3" cellspacing="0" border="2" width="100%"> | <table cellpadding="3" cellspacing="0" border="2" width="100%"> | ||
| Line 132: | Line 101: | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
| − | <td | + | <td width="287">plugin_commentsupport_<plugin name></td> |
| − | + | <td width="602">This function does not take any parameters but simply returns true if this plugin supports comments. This call is made in Geeklog code (example article.php) to determine if it should redirect handling to the plugin</td> | |
| − | |||
| − | <td width="602">This function does not | ||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td width="287">plugin_handlecomment_<plugin | <td width="287">plugin_handlecomment_<plugin | ||
name></td> | name></td> | ||
| − | <td width="602">This | + | <td width="602">This function expects a parameter for the comment id and operation. The operation parameter is either 'save' or 'delete'. This function will update the plugin record with the total number of comments for this plugin item and the then redirect the user back to the plugin instead of the main site page</td> |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
| − | <td width="287">plugin_commentform_<plugin | + | <td width="287">plugin_commentform_<plugin name></td> |
| − | + | <td width="602">This function expects a number of parameters and is called from Geeklog article.php and comment.php. Parameters are: comment_id (primary key), comment_mode (nested, flat, threaded, none), order (Ascending or Descending) and reply (was the reply submit button used on the comment bar). Only comment_id is mandatory.</td> | |
| − | <td width="602">This function expects a | ||
| − | |||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
| − | <td width="287"> | + | <td width="287">plugin_commentparent_<plugin name></td> |
| − | + | <td width="602">Optional function which can be called from your plugin_commentform function to also display the plugin parent above the comments. This is how Geeklog articles are displayed with the story and then the comment bar and associated comments.</td> | |
| − | |||
| − | <td width="602">Optional function which | ||
| − | |||
| − | |||
| − | |||
| − | |||
</tr> | </tr> | ||
</table> | </table> | ||
| − | [[Category:Plugin Development]] | + | |
| + | [[Category:Plugin Developers Handbook]] [[Category:Plugin Development]] | ||
Revision as of 09:11, 5 May 2009
The following section outlines the Geeklog Plugin API functions which you have available to integrate your project or extend your projects features. The only mandatory function is the uninstall function. If any of the functions are not implemented they will be be skipped when Plugin feature is checked from within Geeklog. For example, when building the user menu, all enabled plugins are checked to see if the plugin_getuseroption_pluginname exists. If for plugin mycontacts the plugin_getuseroption_mycontacts() does not exist, it is skipped and the next enabled plugin is checked.
Core Plugin Functions
There are several core functions that are normally always implemented for plugins. Function prototypes and sample code for all these functions are available in the Universal Plugin Kit. If you want to enable any of them just modify the code to fit your plugin and uncomment the code.
| Function | Description of Function |
|---|---|
| plugin_getmenuitems_{plugin} | This places items on the Site Menu |
| plugin_commentsupport_{plugin} | Indicates to Geeklog whether or not this plugin supports Comments |
| plugin_showstats_{plugin} | This expands the Site Stats page. |
| plugin_cclabel_{plugin} | This puts an option for the Plugin in the Command and Control Block |
| plugin_getadminoption_{plugin} | This places a menu option in the Admin Block |
| plugin_getuseroption_{plugin} | This places a menu option in the User Block |
| plugin_uninstall_{plugin} | This uninstalls the plugin and is called by both your install page and the plugin administration page. |
Optional Functions
The following optional plugin functions are broken out into the following related groupings. The first group are the functions required to support moderation within your plugin. If you want your plugin to be moderated like Geeklog stories and links then you must implement these functions.
| Function | Description of Function |
|---|---|
| plugin_ismoderator_<plugin name> | Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise. |
| plugin_submissioncount_<plugin name> | Calculates the current number of submissions awaiting moderation and returns that number. |
| plugin_savesubmission_{plugin name} | Saves submitted item from a user in {plugin name}submission table |
| plugin_moderationvalues_{plugin name} | Returns the primary key column name, the main table name (called {plugin name}) and the list of fields from that table that you'd like to have show up on the moderation page. |
| plugin_itemlist_{plugin name} | Shows any items needing moderation for your plugin on moderation.php |
| plugin_submit_{plugin name} | Shows the submission form for your plugin. Returns a string containing the HTML to display the plugin submission form. |
| plugin_moderationapprove_{plugin name} | Takes an ID into {plugin name}submission and moves it to the main table called {plugin name}. This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin. |
| plugin_moderationdelete_{plugin name} | Takes an ID into {plugin name}submission table and deletes it. This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin. |
If you want your plugin to retrieve search results when the Geeklog search is used or present your plugin as a possible search type then you will want to implement these functions.
| Function | Description of Function |
|---|---|
| plugin_getsearchtypes_{plugin name} | You will probably want to add a new type in the Type drop down on search.php. This function prints the option tags needed. Make sure that the value tag is {plugin name} |
| plugin_dopluginsearch_{plugin name} | Takes the search criteria and lets you build search results for your plugin. This returns a string array of table rows, one row for each record returned by your search. |
If you want your plugin to support comments and use the Geeklog comment engine, then you need to implement these functions in your plugin functions.inc file
| Function | Description of Function |
|---|---|
| plugin_commentsupport_<plugin name> | This function does not take any parameters but simply returns true if this plugin supports comments. This call is made in Geeklog code (example article.php) to determine if it should redirect handling to the plugin |
| plugin_handlecomment_<plugin name> | This function expects a parameter for the comment id and operation. The operation parameter is either 'save' or 'delete'. This function will update the plugin record with the total number of comments for this plugin item and the then redirect the user back to the plugin instead of the main site page |
| plugin_commentform_<plugin name> | This function expects a number of parameters and is called from Geeklog article.php and comment.php. Parameters are: comment_id (primary key), comment_mode (nested, flat, threaded, none), order (Ascending or Descending) and reply (was the reply submit button used on the comment bar). Only comment_id is mandatory. |
| plugin_commentparent_<plugin name> | Optional function which can be called from your plugin_commentform function to also display the plugin parent above the comments. This is how Geeklog articles are displayed with the story and then the comment bar and associated comments. |
