![]() |
Developer Documentation
- Plugin Development |
Overview 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:
Functions for writing plugins 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 Moderation functions 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.
Admin and User functions If you want your plugin to effect the Admin and User Function blocks that show up on every Geeklog page then you must implement thse functions.
Search Functions If you want your plugin to be searchable, implement these functions.
Stats Function If you want your plugin to show up on the stats page then you must implement thse functions.
Implementing your Admin Interface 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 <plugin name>.php and it must be in the above directory. Whether or not you use more that one page for you 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. Preparing your Geeklog Plugin Distribution The plugin tarfile All Geeklog plugin tarfiles MUST use the following naming convention: <plugin name>_<plugin version>_<geeklog version>.tar.gz Descriptions <plugin name>: this is one of the single most important values you will choose for your plugin as it dictates the following:
<geeklog version>: this is the geeklog version the plugin works under. 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: config.php: configuration page for your plugin. We'd prefer you to data-drive most the values if possible but using config.php is fine. This file can be called whatever you want...you are not restricted. functions.inc: this is the file where you implement the Geeklog API and where your plugin code should reside. It MUST be named this because we automatically include all enabled plugins function.inc files at the bottom of common.php. Note that this means you have access to all the functions in common.php in your plugin code. lang.php: the language file for your plugin. You should include this file in your functions.inc. table.sql the DDL needed to modify the Geeklog database so that your plugin will work. NOTE: you must provide an entry in the plugin table in your database. Without it, Geeklog will not know you plugin exists. Example: REPLACE INTO plugins (pi_name, pi_version, pi_gl_version, pi_homepage, pi_enabled) VALUES ('photos', '0.1', '1.2.2', 'http://www.tonybibbs.com', 1); data.sql sample data for your plugin README standard readme for software /docs: includes any documentation you may want to provide for your plugin such as history, to-do, etc /admin: includes only your admininstation pages /public_html: include your regular web pages /updates: includes all update sql and scripts. if you are writing an update SQL script be sure that you name it update_<previous version>.sql. The way this work is if you have version 0.1 installed for a plugin and you are installing version 0.2 the code will look for the update script for the currently isntalled version (0.1) and if it finds it, in this case update_0.1.sql then it will execute it automatically. How Geeklog Installs Plugins There are 2 ways to install plugins. One way is pretty automatic, but not all people can use it due to server setups, so they must install it manually. Below is how the automatic install does it, but the manual install is pretty similar. Assuming you followed the tarfile format from above this is how Geeklog installs the plugin.
Deliver Your Plugin! 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://geeklog.sourceforge.net Description of the Geeklog Plugin API This is the function reference for the Geeklog Plugin API, as contained in the plugins.php file. This is provided strictly for reference sake. You, as a Geeklog Plugin Developer, will not need to modify these functions nor make calls to them as that has already been handled in the Geeklog codebase. We do, however, encourage suggestions on how you think we can make this API better. Moderation Functions These are the functions used to allow your plugin to access the moderation system.
Admin and User options functions These are the functions used to allow your plugin to access the admin and user system
Search functions These are the functions used to allow your plugin to access the search system
Stats functions These are the functions used to allow your plugin to access the stats system
|
The Geeklog Documentation Project
All trademarks and copyrights on this page are owned by their respective owners. GeekLog is copyleft. |