|
| Geeklog Documentation - Plugin Development |
Note: Unfortunately, this document is slightly out of date. While the API functions described in here are still correct, several new functions are missing. If in doubt, please also see the file system/lib-plugins.php which implements the plugin interface.
If you find these API descriptions too terse, you may also want to consult the more extensive Plugin Developers Guide.
Geeklog is becoming more and more popular each day and we, the Geeklog developers, are amazed at some of the great hacks people have made to extend their Geeklog installation to fit their own needs. At the same time, the Geeklog development team is continually adding new features that make Geeklog even better. We have realized the need for Geeklog to support two threads of development: core geeklog code and plugin-code. By building in the infrastructure needed to extend Geeklog's functionality through plugins we can make a clean seperation between the Geeklog codebase and plugin code so that we can concentrate on making Geeklog's core code better while others can develop plugins so that Geeklog fits their needs. With that said, Geeklog now has a Plugin application program interface (API).
At the highest level, the Geeklog Plugin API is generic code that is called in strategic places in the Geeklog codebase that allow function of plugins to be called. This will allow your plugin the following features:
The below functions are what you need to write your own plugin including any extra parameters that you need to pass in. Towards the end of the page, there is also a Description of the API, just incase you need it to help understand in the plugin process.
Note about <plugin name>: You will see references to <plugin name> in all the functions below. The <plugin name> values will come from you the name of your plugin tarfile. All plugin tarfiles have a strict naming convention that they must follow and it is:
<plugin name>_<plugin version>_<geeklog version>.tar.gz
e.g. photos_1.0_1.3.tar.gz
First note that there are limitations in the current Geeklog codebase that will force you to name your plugin tables used for submission in a specific manner. All moderated Geeklog items such as stories and links are comprised of two tables. The first is a main table where all visible items are stored. The second is a submission table where submitted user items sit until an administrator approves them. When approved the item is moved from the submission table to the main table. So for example, if you are writing a book review plugin that allows users to submit book reviews then we will pick bookreviews for your main table (this MUST also be your plugin name you pick) and then your submission table MUST be named bookreviewssubmission. Why force the names? Because in the geeklog code the submission table for all stories is coded as <main name>submission. So since we picked bookreviews for our main table (and plugin name) the submission table must be named bookreviewssubmission.
If you want your plugin to be moderated like Geeklog stories and links then you must implement these functions.
| Function | Description of Function |
|---|---|
| plugin_submit_<plugin name> | Shows the submission form for your plugin. |
| plugin_itemlist_<plugin name> | Shows any items needing moderation for your plugin on moderation.php |
| plugin_savesubmission_<plugin name> | Saves submitted item from a user in <plugin name>submission table |
| plugin_moderationdelete_<plugin name> | Takes an ID into <plugin name>submission table and deletes it |
| plugin_moderationapprove_<plugin name> | Takes an ID into <plugin name>submission and moves it to the main table called <plugin name> |
| 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. |
If you want your plugin to effect the Admin and User Function blocks that show up on every Geeklog page then you must implement these functions.
| Function | Description of Function |
|---|---|
| plugin_adminoptions_<plugin name> | Will show options under the Admin Functions block for your plugin |
| plugin_getuseroption_<plugin name> | Will show options under the User Functions block for your plugin |
| plugin_adminedit_<plugin name> | Shows the links at the top of admin/plugins/<plugin name>.php for New and Admin Home. This is for consistency sake only |
| plugin_submissioncount_<plugin name> | Shows the number of submissions pending for you plugin. This is usually just "dbcount(<plugin name>submission);" |
| plugin_cclabel_<plugin name> | Returns array of your plugin image and a label for your plugin. This is called to show your plugin in the command and control block on moderation.php |
If you want your plugin to be searchable, 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 the comment id (primary index in the comment table) and and type of operation (either 'save' or 'delete') to perform on the comment. It will update the plugin record with the total number of comments for this plugin item. It then handles the refresh or redirection of 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. |
If you want your plugin to show up on the stats page then you must implement this function.
| Function | Description of Function |
|---|---|
| plugin_showstats_<plugin name> | This function takes a showsitestats flag. If set to 1, this function shows the overall stats for your plugin in the site statistics box. If it is set to 2 it shows the statistic blocks for you plugin (similar to Top Ten Viewed Stories and Top Ten Commented Stories). |
If you want to give your plugin the ability to uninstall itself then you must implement this function.
| Function | Description of Function |
|---|---|
| plugin_uninstall_<plugin name> | This function does not take any parameters. The plugin should try and uninstall itself, especially removing all its tables and data structures from the database. The function should return true if the uninstall succeeded and false if it failed. |
For some plugins, it may be necessary to track creation and deletion of user accounts.
| Function | Description of Function |
|---|---|
| plugin_user_create_<plugin name> | This function is called when a new user account has been created. The only parameter passed is the user id. This function does not have a return value. |
| plugin_user_delete_<plugin name> | This function is called when a user account has been deleted. The only parameter passed is the user id. This function does not have a return value. |
Plugins can add blocks or individual items to the user profile.
| Function | Description of Function |
|---|---|
| plugin_profilevariablesedit_<plugin name> | This function is called when Geeklog is about to display the edit form for a user's profile. The plugin is given the user id and a reference to the template of the edit form. It can now add its own variables and input fields to the form. This function does not return anything. The plugin should use the template functions ( set_var etc.) to add things to the template. |
| plugin_profileblocksedit_<plugin name> | This function is called when Geeklog is about to display the edit form for a user's profile. The user id is passed as a parameter to this function. The plugin can return the HTML for a block (including block header and footer) that it wants to be displayed on the profile edit form. When a plugin asks for several items, it may make more sense to group the items this way. Otherwise, you may want to use plugin_profilevariablesedit_<plugin name> (see above) instead.The function is expected to return the HTML for a block or an empty string. |
| plugin_profilevariablesdisplay_<plugin name> | This function is called when Geeklog is about to display a user's profile. The plugin is given the user id and a reference to the template of the profile. It can now add its own variables to the profile. This function does not return anything. The plugin should use the template functions ( set_var etc.) to add things to the template. |
| plugin_profileblocksdisplay_<plugin name> | This function is called when Geeklog is about to display a user's profile. The plugin is given the user id and can now return the HTML for any additional blocks that it wants to be displayed on the profile page. The function is expected to return the HTML for a block or an empty string. |
The following is a list of (optional) functions for misc. purposes.
| Function | Description of Function |
|---|---|
| plugin_centerblock_<plugin name> | Plugins can display a block in the site's center area, i.e. among the stories. This function is called several times during rendering of the site's index page. The parameters will tell the plugin where on the index page the block would appear. Parameters are where (1 = top of page, 2 = after the featured story, 3 = bottom of page), page number and the topic id. where can also be 0 which means that the plugin can take over the entire page if it wants to (in this case, it will have to return the HTML for the entire page, i.e. including site header and footer).The function should return the complete HTML for the block (including header and footer) or an empty string. |
| plugin_getheadercode_<plugin name> | Plugins may add additional lines to the site's <head> tag by implementing this function, e.g. Javascript functions or additional Meta tags.The function should return a concatenated string of all its extra header code. |
| plugin_templatesetvars_<plugin name> | Plugins may set additional template variables. Currently this function is only called in COM_siteHeader and COM_siteFooter, but could in the future be called in other locations. The parameters passed are the template name and the reference to the template object. The plugin API can check the template name (in this case it will currently be 'header' or 'footer') and then using the passed template object reference - set any required new template variables. |
| plugin_whatsnewsupported_<plugin name> | Plugins can add their own section to Geeklog's What's New block by implementing this and the following function. The function should return an array of 2 strings. The first string is used as the headline for the plugin's section in What's New and the second string is used to indicate the timespan that the entries in this section cover (e.g. "last 2 weeks"). |
| plugin_getwhatsnew_<plugin name> | This function should return the actual new entries to be listed in the What's New block (as an array) or a string to be displayed in case there are no new entries. |
| plugin_chkVersion_<plugin name> | Plugins should implement this function and return the code version. Plugins should use a variable in the plugins config.php for the code version which allows the developer to easily update it before releasing a new version. As of Geeklog 1.3.10, this API function is called in the plugin Editor to show the version of the current installed version and plugin code version. The plugin installed version is pulled from the plugins table and should be updated as part of the plugin install or future updates. This API function allows the site admin to know if the current plugin code is newer then the installed version. Plugin developers can read the installed version from the plugins table and determine automatically if any SQL updates are required or atleast update the plugin record to be the same as the code version. |
| plugin_runScheduledTask_<plugin name> | This function allows plugin developers to schedule a task to be run. This API will only be called when someone accesses the site but should be sufficient for most plugins that want to schedule some maintenance process or clean-up routine. The interval this API is called is set in the site's config.php and all plugins that have this function will then be called. |
The following is a list of (optional) functions for syndication feed purposes.
| Function | Description of Function |
|---|---|
| plugin_getfeednames_<plugin name> | Plugins can provide content for the creation of syndication feeds. This function allows the plugin to return a list of feed content it can supply. For example, the links plugin provides a feed for all links, and a feed for each link category. The plugin should return an array of id/name pairs where id is the plugins internal id for the field and name is what is displayed to the user. |
| plugin_getfeedcontent_<plugin name> | Where a plugin has returned a list of feeds from the plugin_getfeednames_<plugin name> function, it must also return feed content using this function. The plugin is expected to return an array holding the content of the feed and to fill in 'link' (some link that represents the same content on the site as that in the feed) and 'update_data' (to be stored for later up-to-date checks). |
| plugin_feedExtensionTags_<plugin name> | Plugins may enter additional elements in the top level of a feed format by supporting this function. The function receives the type and version of a feed (e.g. RSS version 2.0) and is expected to return an array of valid XML tags. (See the Syndication Extensions plugin for an example.) |
| plugin_feedNSExtensions_<plugin name> | Plugins which add their own elements to feeds may require extra XML Namespaces adding to the XML. This function should return an array of valid namespace attributes. (See the Syndication Extensions plugin for an example.) |
| plugin_feedElementExtensions_<plugin name> | Plugins may add additional elements to feed items by supporting this function. The function is supplied the version and type of feed, plus the content type and identifier and must return an array of valid XML Elements. (See the Syndication Extensions plugin for an example.) |
The Geeklog Plugin API is just that an API. You obviously have to write all your plugin code yourself. We have put stubs in place to link to you Admin Interface. You admin page(s) will be in http://yourgeeklogdomain/admin/plugins/<plugin name>/
The first page of your administration interface must be named index.php and it must be in the above directory. Whether or not you use more than one page for your Admin interface is completely up to you.
Please note that the location of your admin page isn't optional. For organizational purposes it is important that you follow the standards outlined in this document.
All Geeklog plugin tarfiles should use the following naming convention:
<plugin name>_<plugin version>_<geeklog version>.tar.gz
The organization of your tarfile is standardized as well. For each directory and file a description is given. Your base plugin directory when you create the tarfile should be <plugin name>. Under there you will have the following:
Note: Up until Geeklog version 1.3.4, there was an automatic install procedure for plugins. This, however, caused too many problems and support issues and has been removed from later versions. The manual install as outlined below is now the recommended way to install a plugin and should work for both old and new versions of Geeklog.
For details, you should always refer to the README that comes with the plugin. A general overview of plugins and install details is also provided as part of the Geeklog Documentation Project here . In general, however, a plugin will be installed like this:
Because Geeklog Plugins can affect a Geeklog installation and the users filesystem, our policy is we will not endorse third party plugins unless they have been tested by the Geeklog Development team. Why? We will make sure that your plugin installs successfully and doesn't have any adverse behavior. Assuming your plugin checks out, we will put your tarfile on our site where it can be downloaded by Geeklog users. You can sumbit your plugin to our site at http://www.geeklog.net/
| The Geeklog Documentation Project All trademarks and copyrights on this page are owned by their respective owners. GeekLog is copyleft. |