[Sommaire] [Imprimer]

   1  This file was last updated on November 13th, 2001
   2  
   3  This README will explain how you can quickly develop Geeklog Plug-ins.  Please take the time to read this as this will save you time and possibly trouble with getting your Geeklog Plug-in to work.
   4  
   5  Contents
   6  --------
   7  1) Overview of Geeklog Plugin Implementation
   8  2) Description of the Geeklog Plugin API
   9  3) Plugin Functions You Implement
  10  4) Implementing your Admin Interface
  11  5) Preparing your Geeklog Plugin Distribution
  12  6) Deliver Your Plugin!
  13  
  14  1) Overview of Geeklog Plugin Implementation
  15  --------------------------------------------
  16  
  17  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).
  18  
  19  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:
  20  
  21  - Ability for your plugin to be submission-based so that users can submit objects to your plug-in.  You can then visit the command and control center in Geeklog to moderate the submissions for your plugin
  22  
  23  - Allow your plugin to show up in the Admin block and User block on each Geeklog page
  24  
  25  - Allow your plugin to be searched via the Geeklog search page
  26  
  27  - Allow stats for your plugin to show up on the site statistics page
  28  
  29  - Allow your plugin the ability to use Geeklog's comment engine
  30  
  31  - Allow you to use the power of Geeklog's code library (common.php) in your own plugin code
  32  
  33  - Allow you full flexibility on what your plugin does
  34  
  35  2) Description of the Geeklog Plugin API
  36  ----------------------------------------
  37  
  38  This is the function reference for the Geeklog Plugin API.  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.
  39  
  40  Moderation Functions
  41  --------------------
  42  
  43  These are the functions used to allow your plugin to moderation-based
  44  
  45  Function: SubmitPlugin
  46  Description: This function loops through all enabled plugins and calls the plugins plugin_submit_<plugin name> method so that a plugins submission form is shown to the user.
  47  
  48  Function: GetPluginModerationValues
  49  Description: Responsible for calling the plugin_moderationvalue_<plugin name> method so that the plugin specific values can be set so that moderation can occur.
  50  
  51  Function: ShowPluginModerationLists
  52  Description: Loops through all enabled plugins and call itemlist() so that all items needing moderation for the plugin shows up in moderation.php
  53  
  54  Function: ShowPluginModerationOptions
  55  Description: Loops through all enabled plugins and calls the plugin_cclabel_<plugin name> method so the plugin shows in the command and control center.
  56  
  57  Function: SavePluginSubmission
  58  Description: Loops through all enabled plugins and calls the plugin_savesubmission_<plugin name> method so that the plugin submission for a specified plugin gets saved.
  59  
  60  Function: DoPluginModerationDelete
  61  Description: Calls the plugin_moderationdelete_<plugin name> method of a specifid plugin so that a submission is deleted
  62  
  63  Function: DoPluginModerationApprove
  64  Description: Calls the plugin_moderationapprove_<plugin name> method of a specified plugin so that the submission is approved
  65  
  66  These are the functions to implement admin and user options for plugins
  67  -----------------------------------------------------------------------
  68  
  69  Function: ShowPluginAdminOptions
  70  Description: Loops through all enabled plugins and calls their plugin_showadminoption_<plugin name> so that the plugin shows any option(s) they need under the Admin block.
  71  
  72  Function: ShowPluginUserOptions
  73  Description: Loops through all enabled plugins and calls their plugin_getuseroption_<plugin name> so that the plugin shows any option(s) users need in their User Functions block
  74  
  75  Function: HandlePluginAdminEdit
  76  Description: calls the plugin_adminedit_<plugin name> method so that the "new <plugin name> | Admin Home" links show up at the top of admin/plugins/<plugin name>.php.  This is implemented strictly for consistency of the UI
  77  
  78  Function: GetPluginSubmissionCounts
  79  Description: loops through all enabled plugins and calls their plugin_submissioncount_<plugin name> method so that the number of submissions for plugins gets displayed
  80  
  81  These functions implement searching functionality for plugins
  82  -------------------------------------------------------------
  83  
  84  Function: GetPluginSearchTypes 
  85  Description: loops through all enabled plugins and calls their plugin_getsearchtypes_<plugin name> method to get any plugin specific values that need to show up in the Type drop down on search.php
  86  
  87  Function: DoPluginSearches
  88  Description: loops through all enabled plugins and submits the search criteria to the plugin_dopluginsearch_<pluginname> method so that the plugin can perform it's own search
  89  
  90  This function implements showing statistics for plugins on the site statistics page
  91  -----------------------------------------------------------------------------------
  92  
  93  Function: Show Plugin Stats
  94  Description: loops through all enabled plugins and calls the plugin's plugin_showstats_<plugin name> method so that statistics can be reported for the plugin
  95  
  96  3) Plugin Functions You Implement
  97  ---------------------------------
  98  
  99  The best way to learn how to implement a Geeklog plugin is to use an existing plugin, see how it works and change it to fit your needs.  Included with this distribution of Geeklog is a sample plugin file called ?? that you can install so that you have a working example of a Geeklog plugin to work from.
 100  
 101  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:
 102  
 103  <plugin name>_<plugin version>_<geeklog version>.tar.gz
 104  
 105  e.g. photos_0.1_1.2.2.tar.gz
 106  
 107  MODERATION IMPLEMENTATION
 108  -------------------------
 109  
 110  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.
 111  
 112  Moderation Functions: If you want your plugin to be moderated like Geeklog stories and links then you
 113  must implement these functions.  
 114  
 115  Function: plugin_submit_<plugin name>
 116  Description: shows the submission form for your plugin
 117  
 118  Function: plugin_itemlist_<plugin name>
 119  Descriptions:  shows any items needing moderation for your plugin on moderation.php
 120  
 121  Function: plugin_savesubmission_<plugin name>
 122  Description: saves submitted item from a user in <plugin name>submission table
 123  
 124  Function: plugin_moderationdelete_<plugin name>
 125  Description: takes an ID into <plugin name>submission table and deletes it
 126  
 127  Function: plugin_moderationapprove_<plugin name>
 128  Description: takes an ID into <plugin name>submission and moves it to the main table called <plugin name>
 129  
 130  Function: plugin_moderationvalues_<plugin name>
 131  Description: 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.
 132  
 133  ADMIN/USER UI CHANGES
 134  ---------------------
 135  
 136  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
 137  
 138  Function: plugin_adminoptions_<plugin name>
 139  Description: will show options under the Admin Functions block for your plugin
 140  
 141  Function: plugin_showuseroptions_<plugin name>
 142  Description: will show options under teh User Functions block for your plugin
 143  
 144  Function: plugin_adminedit_<plugin name>
 145  Description: Shows the links at the top of admin/plugins/<plugin name>.php for New and admin home. This is for consistency sake only
 146  
 147  Function: plugin_submissioncount_<plugin name>
 148  Description: Shows the number of submissions pending for you plugin.  This is usually just "dbcount(<plugin name>submission);"
 149  
 150  Function: plugin_cclabel_<plugin name>
 151  Description: 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
 152  
 153  SEARCH FUNCTIONS
 154  ----------------
 155  
 156  If you want your plugin to be searchable, implement these functions
 157  
 158  Function: plugin_getsearchtypes_photos
 159  Description: you will probably want to add a new type in teh Type drop down on search.php.  This function prints the option tags needed. make sure that the value tag is <plugin name>
 160  
 161  Function: plugin_dopluginsearch_<plugin name>
 162  Description: 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.
 163  
 164  Function: plugin_showstats_<plugin name>
 165  Description: 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 Stroes).
 166  
 167  4) Implementing your Admin Interface
 168  ------------------------------------
 169  
 170  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>/
 171  
 172  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.  
 173  
 174  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.
 175  
 176  5) Preparing your Geeklog Plugin Distribution
 177  ---------------------------------------------
 178  
 179  The plugin tarfile
 180  ------------------
 181  
 182  All Geeklog plugin tarfiles MUST use the following naming convention:
 183  
 184  <plugin name>_<plugin version>_<geeklog version>.tar.gz
 185  
 186  Descriptions
 187  
 188  <plugin name>: this is one of the single most important values you will choose for your plugin as it dictates the following:
 189  - the exact API function names that the Geeklog code will try to call for your plugin
 190  - the exact directory within the webtree to put all your plugin code
 191  - the exact directory within the admin directory to put your admin code
 192  - if using moderation, the exact table name main table being moderated
 193  - if using moderation, the submission table will be <plugin name>submission
 194  
 195  <plugin version>: used during the installation process to determine if you are attempting to upgrade a plugin or do a new installation. It is also check to verify that you aren't trying to install and old version of the plugin when a new installation already exists.
 196  
 197  <geeklog version>: this is the geeklog version the plugin works under.
 198  
 199  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:
 200  
 201  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.
 202  
 203  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 haveaccess to all the functions in common.php in your plugin code.
 204  
 205  lang.php: the language file for your plugin.  You should include this file in your functions.inc.
 206  
 207  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:
 208  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);
 209  
 210  data.sql sample data for your plugin
 211  
 212  README standard readme for software
 213  
 214  /docs: includes any documentation you may want to provide for your plugin such as history, to-do, etc
 215  
 216  /admin: includes only your admininstation pages
 217  
 218  /public_html: include your regular web pages
 219  
 220  /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
 221  
 222  How Geeklog Installs Plugins
 223  ----------------------------
 224  
 225  Assuming you followed the tarfile format from above this is how Geeklog installs the plugin.
 226  
 227  1) when use submits the tarfile from admin/plugins.php, the tarfile is copied to /path/to/geeklog/plugins/
 228  2) the tarfile is uncompressed
 229  3) the public_html directory in the tarfile is copied to the webtree under <plugin name>. e.g. if my geeklog web is in /path/to/geeklog/public_html/ then the public_html from the tarfile is copied to /path/to/geeklog/public_html/<plugin name>
 230  4) the admin directory in the tarfile is copied to the admin webtree.  e.g. if my geeklog admin webtree is in /path/to/geeklog/public_html/admin/ then the admin directory from the tarfile is copied to /path/to/geeklog/public_html/admin/plugins/<plugin name>  
 231  5) if this is a new install (plugin doesn't exist in plugins table) then table.sql is executed and then data.sql is executed
 232  6) if this is an upgrade that the necessary upgrade_<version>.sql script is searched for and, if found, executed.
 233  
 234  That's it!
 235  
 236  6) Deliver Your Plugin!
 237  -----------------------
 238  
 239  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