[Sommaire] [Imprimer]

   1  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2  <html>
   3  <head>
   4    <title>Geeklog Documentation - Plugin Development</title>
   5    <link rel="stylesheet" type="text/css" href="docstyle.css" title="Dev Stylesheet">
   6  </head>
   7  
   8  <body>
   9  <table cellpadding="2" cellspacing="2" border="0" width="100%">
  10  <tr>
  11    <td valign="top"><img src="images/newlogo.gif" alt="Geeklog Documentation" width="243" height="90" border="0"></td>
  12  </tr>
  13  <tr>
  14    <td valign="top" class="menu"><a href="index.html">Geeklog Documentation</a> - Plugin Development</td>
  15  </tr>
  16  </table>
  17  
  18  <h1>Plugin Development</h1>
  19  
  20  <p><strong>Note:</strong> Unfortunately, this document is slightly out of date.
  21  While the API functions described in here are still correct, several new
  22  functions are missing. If in doubt, please also see the file
  23  <tt>system/lib-plugins.php</tt> which implements the plugin interface.</p>
  24  
  25  <p>If you find these API descriptions too terse, you may also want to consult
  26  the more extensive <a href="http://gplugs.sourceforge.net/pluginman/">Plugin
  27  Developers Guide</a>.</p>
  28  
  29  <ul>
  30    <li><a href="#overview">Overview</a></li>
  31    <li><a href="#Functions_for_writing">Geeklog Plugin API Functions</a>
  32      <ul>
  33        <li><a href="#mod_functions">Moderation Functions</a></li>
  34        <li><a href="#admin_user_functions">Admin and User Menu Functions</a></li>
  35        <li><a href="#Search_Functions">Search Functions</a></li>
  36        <li><a href="#Comment_Functions">Comment Functions</a></li>
  37        <li><a href="#Stats_Function">Stats Function</a></li>
  38        <li><a href="#Uninstall_Function">Uninstall Function</a></li>
  39        <li><a href="#User_Functions">User Functions</a></li>
  40        <li><a href="#Profile_Functions">Profile Functions</a></li>
  41        <li><a href="#Misc_Functions">Misc. Functions</a></li>
  42        <li><a href="#Feed_Functions">Feed Functions</a></li>
  43      </ul></li>
  44    <li><a href="#Implementing_your_Admin_Interface">Implementing your Admin Interface</a></li>
  45    <li><a href="#Preparing_your_Geeklog_Plugin">Preparing your Geeklog Plugin Distribution</a></li>
  46    <li><a href="#How_Geeklog_Installs_Plugins">How To Install A Geeklog Plugin</a></li>
  47    <li><a href="#Deliver_Your_Plugin">Deliver Your Plugin!</a></li>
  48  </ul>
  49  
  50  <h2><a name="overview">Overview</a></h2>
  51  
  52  <p>Geeklog is becoming more and more popular each day and   we,   the
  53  Geeklog developers,  are amazed at some of the great  hacks   people   have
  54  made to extend   their Geeklog  installation to fit their   own
  55  needs.&nbsp;     At the  same time,   the Geeklog development  team is
  56  continually adding   new  features  that make   Geeklog even better. We
  57  have realized the   need  for Geeklog  to support   two threads of
  58  development:  core geeklog  code and  plugin-code. By building  in the
  59  infrastructure   needed to  extend Geeklog's  functionality  through
  60  plugins  we can make  a clean seperation    between the  Geeklog codebase
  61  and plugin code  so that we can concentrate    on making Geeklog's  core
  62  code  better while others     can develop plugins   so that Geeklog fits
  63  their needs. With that    said,  Geeklog now has   a Plugin application
  64  program interface (API).
  65  
  66  <p>At the highest level, the Geeklog Plugin API is generic     code   that
  67  is  called   in strategic places in the Geeklog codebase  that   allow   function
  68  of plugins to be called. This will allow your plugin the following features:
  69  
  70  <ul>
  71    <li>Ability for your plugin to be submission-based so that users can submit
  72      objects to your plugin.&nbsp; You can then visit the command and
  73      control center in Geeklog to moderate the submissions for your plugin.</li>
  74    <li>Allow your plugin to show up in the Admin block and User block on each
  75      Geeklog page.</li>
  76    <li>Allow your plugin to be searched via the Geeklog search page.</li>
  77    <li>Allow stats for your plugin to show up on the site statistics page.</li>
  78    <li> Allow your plugin the ability to use Geeklog's comment engine.</li>
  79    <li>Allow you to use the power of Geeklog's code library (lib-common.php) in
  80      your own plugin code.</li>
  81    <li>Allow you full flexibility on what your plugin does. Geeklog does not
  82      dictate your plugins power.</li>
  83  </ul>
  84  
  85  <h2><a name="Functions_for_writing">Functions for writing plugins</a></h2>
  86  
  87  <p>The below functions are what you need to write your own plugin including
  88  any extra parameters that you need to pass in. Towards the end of the
  89  page,    there is also a Description of the API, just incase you need it to
  90  help  understand  in the plugin process.
  91  
  92  <p>
  93  <strong>Note about &lt;plugin name&gt;:</strong> You will see references to
  94  &lt;plugin name&gt; in all the functions below.&nbsp; The &lt;plugin
  95  name&gt; values will come from you the name of your plugin tarfile. All plugin
  96  tarfiles have a strict naming convention that they <em>must</em> follow and it is:
  97  
  98  <blockquote>
  99    &lt;plugin name&gt;_&lt;plugin version&gt;_&lt;geeklog version&gt;.tar.gz<br>
 100    e.g. <tt>photos_1.0_1.3.tar.gz</tt>
 101  </blockquote>
 102  
 103  <h2><a name="mod_functions">Moderation functions</a></h2>
 104  
 105  <p>First note that there are limitations in the current Geeklog codebase that
 106  will force you to name your plugin tables used  for submission in a
 107  specific manner.&nbsp; All moderated Geeklog items such  as stories and
 108  links are comprised of two tables.&nbsp; The first is a main  table where
 109  all visible items are stored.&nbsp; The second is a submission table where
 110  submitted user items sit until an administrator approves them.&nbsp; When
 111  approved the item is moved from the submission table to the main
 112  table.&nbsp;    So for example, if you are writing a book review plugin
 113  that  allows users    to submit book reviews then we will pick bookreviews
 114  for your main table   (this MUST also be your plugin name you pick) and
 115  then your submission table   MUST be named bookreviewssubmission.&nbsp; Why
 116  force the names? Because in  the geeklog code the submission table for all
 117  stories is coded as &lt;main   name&gt;submission.&nbsp; So since we picked
 118  bookreviews for our main table   (and plugin name) the submission table
 119  must be named&nbsp; bookreviewssubmission.
 120  
 121  <p>If you want your plugin to be moderated like Geeklog stories
 122  and links then you must implement these functions.</p>
 123  
 124  <table cellpadding="2" cellspacing="2" border="1" width="90%" align="center">
 125  <caption align="bottom">Table 1. Moderation functions<br></caption>
 126  <tr>
 127    <th valign="top">Function</th>
 128    <th valign="top">Description of Function</th></tr>
 129  <tr>
 130    <td valign="top" class="codeheader">plugin_submit_&lt;plugin name&gt;</td>
 131    <td valign="top" class="code">Shows the submission form for your plugin.</td>
 132    </tr>
 133  <tr>
 134    <td valign="top" class="codeheader">plugin_itemlist_&lt;plugin name&gt;</td>
 135    <td valign="top" class="code">Shows any items needing moderation for your plugin on moderation.php</td>
 136    </tr>
 137  <tr>
 138    <td valign="top" class="codeheader">plugin_savesubmission_&lt;plugin name&gt;</td>
 139    <td valign="top" class="code">Saves submitted item from a user in &lt;plugin name&gt;submission table</td>
 140    </tr>
 141  <tr>
 142    <td valign="top" class="codeheader">plugin_moderationdelete_&lt;plugin name&gt;</td>
 143    <td valign="top" class="code">Takes an ID into &lt;plugin name&gt;submission table and deletes it</td>
 144    </tr>
 145  <tr>
 146    <td valign="top" class="codeheader">plugin_moderationapprove_&lt;plugin name&gt;</td>
 147    <td valign="top" class="code">Takes an ID into &lt;plugin name&gt;submission and moves it to the main table called &lt;plugin name&gt;</td>
 148    </tr>
 149  <tr>
 150    <td valign="top" class="codeheader">plugin_moderationvalues_&lt;plugin name&gt;</td>
 151    <td valign="top" class="code">Returns the primary key column name, the main
 152      table name (called &lt;plugin name&gt;) and the list of fields from that
 153      table that you'd like to have show up on the moderation page.</td>
 154    </tr>
 155  </table>
 156  
 157  <h2><a name="admin_user_functions">Admin and User Menu functions</a></h2>
 158  
 159  <p>If you want your plugin to effect the Admin and User Function blocks
 160  that show up on every Geeklog page then you must implement these
 161  functions.</p>
 162  
 163        <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 164          <caption align="bottom">Table 2. Admin and User functions</caption>
 165            <tr>
 166              <th valign="top">Function</th>
 167              <th valign="top">Description of Function</th>
 168            </tr>
 169            <tr>
 170              <td valign="top" class="codeheader">plugin_adminoptions_&lt;plugin name&gt;</td>
 171              <td valign="top" class="code">Will show options under the Admin
 172        Functions block for your plugin</td>
 173            </tr>
 174            <tr>
 175              <td valign="top" class="codeheader">plugin_getuseroption_&lt;plugin
 176        name&gt;</td>
 177              <td valign="top" class="code">Will show options under the User
 178        Functions block for your plugin</td>
 179            </tr>
 180            <tr>
 181              <td valign="top" class="codeheader">plugin_adminedit_&lt;plugin
 182        name&gt;</td>
 183              <td valign="top" class="code">Shows the links at the top of admin/plugins/&lt;plugin
 184       name&gt;.php for New and Admin Home. This is for consistency sake only</td>
 185            </tr>
 186            <tr>
 187              <td valign="top" class="codeheader">plugin_submissioncount_&lt;plugin
 188        name&gt;</td>
 189              <td valign="top" class="code">Shows the number of submissions
 190        pending for you plugin.&nbsp; This is usually just "dbcount(&lt;plugin
 191     name&gt;submission);"</td>
 192            </tr>
 193            <tr>
 194              <td valign="top" class="codeheader">plugin_cclabel_&lt;plugin
 195        name&gt;</td>
 196              <td valign="top" class="code">Returns array of your plugin image
 197        and a label for your plugin.&nbsp; This is called to show your plugin
 198    in   the command and control block on moderation.php</td>
 199            </tr>
 200        </table>
 201  
 202  <h2><a name="Search_Functions">Search Functions</a></h2>
 203  
 204  <p>If you want your plugin to be searchable, implement these functions.</p>
 205  
 206        <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 207          <caption align="bottom">Table 3. Search functions</caption>
 208            <tr>
 209              <th valign="top">Function</th>
 210              <th valign="top">Description of Function</th>
 211            </tr>
 212            <tr>
 213              <td valign="top" class="codeheader">plugin_getsearchtypes_&lt;plugin
 214       name&gt;</td>
 215              <td valign="top" class="code">You will probably want to add a
 216       new type in the Type drop down on search.php.&nbsp; This function prints
 217      the option tags needed. make sure that the value tag is &lt;plugin name&gt;</td>
 218            </tr>
 219            <tr>
 220              <td valign="top" class="codeheader">plugin_dopluginsearch_&lt;plugin
 221       name&gt;</td>
 222              <td valign="top" class="code">Takes the search criteria and lets
 223       you build search results for your plugin.&nbsp; This returns a string
 224   array    of table rows, one row for each record returned by your search.</td>
 225            </tr>
 226        </table>
 227  
 228  <h2><a name="Comment_Functions">Comment Function</a></h2>
 229  
 230  <p>If you want your plugin to support comments and use the Geeklog comment
 231  engine, then you need to implement these functions in your plugin
 232  functions.inc file:</p>
 233  
 234  <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 235  <caption align="bottom">Table 4. Comment functions</caption>
 236    <tr>
 237      <th valign="top">Function</th>
 238      <th valign="top">Description of Function</th>
 239    </tr>
 240    <tr>
 241      <td valign="top" class="codeheader">plugin_commentsupport_&lt;plugin name&gt;</td>
 242      <td valign="top" class="code">
 243      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>
 244    </tr>
 245    <tr>
 246      <td valign="top" class="codeheader">plugin_handlecomment_&lt;plugin name&gt;</td>
 247      <td valign="top" class="code">
 248      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.</td>
 249    </tr>
 250    <tr>
 251      <td valign="top" class="codeheader">plugin_commentform_&lt;plugin name&gt;</td>
 252      <td valign="top" class="code">
 253      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).<br>
 254      Only comment_id is mandatory.</td>
 255    </tr>
 256    <tr>
 257      <td valign="top" class="codeheader">plugin_commentparent_&lt;plugin name&gt;</td>
 258      <td valign="top" class="code">
 259      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>
 260    </tr>
 261  </table>
 262  
 263  
 264  <h2><a name="Stats_Function">Stats Function</a></h2>
 265  
 266  <p>If you want your plugin to show up on the stats page then you must
 267  implement this function.</p>
 268  
 269        <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 270          <caption align="bottom">Table 5. Stats function</caption>
 271            <tr>
 272              <th valign="top">Function</th>
 273              <th valign="top">Description of Function</th>
 274            </tr>
 275            <tr>
 276              <td valign="top" class="codeheader">plugin_showstats_&lt;plugin
 277       name&gt;</td>
 278              <td valign="top" class="code">This function takes a showsitestats
 279       flag.&nbsp; If set to 1, this function shows the overall stats for your
 280     plugin  in the site statistics box.&nbsp; If it is set to 2 it shows the
 281    statistic  blocks for you plugin (similar to Top Ten Viewed Stories and
 282  Top  Ten Commented  Stories).</td>
 283            </tr>
 284        </table>
 285  
 286  <h2><a name="Uninstall_Function">Uninstall Function</a></h2>
 287  
 288  <p>If you want to give your plugin the ability to uninstall itself then you must implement this function.</p>
 289  
 290        <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 291          <caption align="bottom">Table 6. Uninstall function</caption>
 292            <tr>
 293              <th valign="top">Function</th>
 294              <th valign="top">Description of Function</th>
 295            </tr>
 296            <tr>
 297              <td valign="top" class="codeheader">plugin_uninstall_&lt;plugin
 298       name&gt;</td>
 299              <td valign="top" class="code">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.<br>
 300  The function should return <code>true</code> if the uninstall succeeded and <code>false</code> if it failed.</td>
 301            </tr>
 302        </table>
 303  
 304  <h2><a name="User_Functions">User Functions</a></h2>
 305  
 306  <p>For some plugins, it may be necessary to track creation and deletion of user accounts.</p>
 307  
 308    <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center">
 309      <caption align="bottom">Table 7. User functions</caption>
 310        <tr>
 311          <th valign="top">Function</th>
 312          <th valign="top">Description of Function</th>
 313        </tr>
 314        <tr>
 315          <td valign="top" class="codeheader">plugin_user_create_&lt;plugin name&gt;</td>
 316          <td valign="top" class="code">This function is called when a new user account has been created. The only parameter passed is the user id.<br>
 317  This function does not have a return value.</td>
 318        </tr>
 319        <tr>
 320          <td valign="top" class="codeheader">plugin_user_delete_&lt;plugin name&gt;</td>
 321          <td valign="top" class="code">This function is called when a user account has been deleted. The only parameter passed is the user id.<br>
 322  This function does not have a return value.</td>
 323        </tr>
 324    </table>
 325  
 326  <h2><a name="Profile_Functions">Profile Functions</a></h2>
 327  
 328  <p>Plugins can add blocks or individual items to the user profile.</p>
 329  
 330    <table cellpadding="2" cellspacing="2" border="1" width="90%" align="center">
 331      <caption align="bottom">Table 8. Profile Functions</caption>
 332        <tr>
 333          <th valign="top">Function</th>
 334          <th valign="top">Description of Function</th>
 335        </tr>
 336        <tr>
 337          <td valign="top" class="codeheader">plugin_profilevariablesedit_&lt;plugin name&gt;</td>
 338          <td valign="top" class="code">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.<br>
 339  This function does not return anything. The plugin should use the template functions (<code>set_var</code> etc.) to add things to the template.</td>
 340        </tr>
 341        <tr>
 342          <td valign="top" class="codeheader">plugin_profileblocksedit_&lt;plugin name&gt;</td>
 343          <td valign="top" class="code">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 <code>plugin_profilevariablesedit_&lt;plugin name&gt;</code> (see above) instead.<br>
 344  The function is expected to return the HTML for a block or an empty string.</td>
 345        </tr>
 346        <tr>
 347          <td valign="top" class="codeheader">plugin_profilevariablesdisplay_&lt;plugin name&gt;</td>
 348          <td valign="top" class="code">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.<br>
 349  This function does not return anything. The plugin should use the template functions (<code>set_var</code> etc.) to add things to the template.</td>
 350        </tr>
 351        <tr>
 352          <td valign="top" class="codeheader">plugin_profileblocksdisplay_&lt;plugin name&gt;</td>
 353          <td valign="top" class="code">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.<br>
 354  The function is expected to return the HTML for a block or an empty string.</td>
 355        </tr>
 356      </table>
 357  
 358  <h2><a name="Misc_Functions">Misc. Functions</a></h2>
 359  
 360  <p>The following is a list of (optional) functions for misc. purposes.</p>
 361  
 362    <table cellpadding="2" cellspacing="2" border="1" width="90%" align="center">
 363      <caption align="bottom">Table 9. Misc. functions</caption>
 364        <tr>
 365          <th valign="top">Function</th>
 366          <th valign="top">Description of Function</th>
 367        </tr>
 368        <tr>
 369          <td valign="top" class="codeheader">plugin_centerblock_&lt;plugin name&gt;</td>
 370          <td valign="top" class="code">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.<br>
 371  Parameters are <code>where</code> (1 = top of page, 2 = after the featured story, 3 = bottom of page), <code>page number</code> and the <code>topic id</code>. <code>where</code> 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 <em>entire page</em>, i.e. including site header and footer).<br>
 372  The function should return the complete HTML for the block (including header and footer) or an empty string.</td>
 373        </tr>
 374        <tr>
 375          <td valign="top" class="codeheader">plugin_getheadercode_&lt;plugin
 376       name&gt;</td>
 377          <td valign="top" class="code">Plugins may add additional lines to the site's <code>&lt;head&gt;</code> tag by implementing this function, e.g. Javascript functions or additional Meta tags.<br>
 378  The function should return a concatenated string of all its extra header code.</td>
 379        </tr>
 380        <tr>
 381          <td valign="top" class="codeheader">plugin_templatesetvars_&lt;plugin
 382       name&gt;</td>
 383          <td valign="top" class="code">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.</td>
 384        </tr>
 385      <tr>
 386          <td valign="top" class="codeheader">plugin_whatsnewsupported_&lt;plugin name&gt;</td>
 387          <td valign="top" class="code">Plugins can add their own section to Geeklog's What's New block by implementing this and the following function.<br>
 388          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").</td>
 389      </tr>
 390      <tr>
 391          <td valign="top" class="codeheader">plugin_getwhatsnew_&lt;plugin name&gt;</td>
 392          <td valign="top" class="code">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.</td>
 393      </tr>
 394      <tr>
 395          <td valign="top" class="codeheader">plugin_chkVersion_&lt;plugin name&gt;</td>
 396          <td valign="top" class="code">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.</td>
 397      </tr>
 398      <tr>
 399          <td valign="top" class="codeheader">plugin_runScheduledTask_&lt;plugin name&gt;</td>
 400          <td valign="top" class="code">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.</td>
 401      </tr>
 402  
 403    </table>
 404  
 405    <h2><a name="Feed_Functions">Feed Functions</a></h2>
 406  
 407  <p>The following is a list of (optional) functions for syndication feed purposes.</p>
 408  
 409    <table cellpadding="2" cellspacing="2" border="1" width="90%" align="center">
 410      <caption align="bottom">Table 10. Feed functions</caption>
 411        <tr>
 412          <th valign="top">Function</th>
 413          <th valign="top">Description of Function</th>
 414        </tr>
 415        <tr>
 416          <td valign="top" class="codeheader">plugin_getfeednames_&lt;plugin name&gt;</td>
 417          <td valign="top" class="code">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.</td>
 418        </tr>
 419        <tr>
 420          <td valign="top" class="codeheader">plugin_getfeedcontent_&lt;plugin
 421       name&gt;</td>
 422          <td valign="top" class="code">Where a plugin has returned a list of feeds from the plugin_getfeednames_&lt;plugin name&gt; 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).</td>
 423        </tr>
 424        <tr>
 425          <td valign="top" class="codeheader">plugin_feedExtensionTags_&lt;plugin
 426       name&gt;</td>
 427          <td valign="top" class="code">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 <a href="http://sourceforge.net/project/showfiles.php?group_id=91120&amp;package_id=168689">Syndication Extensions</a> plugin for an example.)</td>
 428        </tr>
 429      <tr>
 430          <td valign="top" class="codeheader">plugin_feedNSExtensions_&lt;plugin name&gt;</td>
 431          <td valign="top" class="code">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 <a href="http://sourceforge.net/project/showfiles.php?group_id=91120&amp;package_id=168689">Syndication Extensions</a> plugin for an example.)</td>
 432      </tr>
 433      <tr>
 434          <td valign="top" class="codeheader">plugin_feedElementExtensions_&lt;plugin name&gt;</td>
 435          <td valign="top" class="code">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 <a href="http://sourceforge.net/project/showfiles.php?group_id=91120&amp;package_id=168689">Syndication Extensions</a> plugin for an example.)</td>
 436      </tr>
 437    </table>
 438  
 439  
 440  <h2><a name="Implementing_your_Admin_Interface">Implementing your Admin Interface</a></h2>
 441  
 442  <p>The Geeklog Plugin API is just that an API.&nbsp; You obviously have   to
 443  write all your plugin code yourself.&nbsp; We have put stubs in place   to
 444  link to you Admin Interface.&nbsp; You admin page(s) will be in
 445  http://yourgeeklogdomain/admin/plugins/&lt;plugin name&gt;/
 446  
 447  <p>The first page of your administration interface must be named
 448  index.php and it must be in the above directory.&nbsp; Whether or not
 449  you use more than one page for your Admin interface is completely up to you.
 450  
 451  <p>Please note that the location of your admin page isn't optional.&nbsp; For
 452  organizational purposes it is important that you follow the standards
 453  outlined  in this document.
 454  
 455  <h2><a name="Preparing_your_Geeklog_Plugin">Preparing your Geeklog Plugin Distribution</a></h2>
 456  
 457  <h3>The plugin tarfile</h3>
 458  
 459  <p>All Geeklog plugin tarfiles should use the following naming convention:
 460  
 461  <blockquote>
 462  &lt;plugin name&gt;_&lt;plugin version&gt;_&lt;geeklog version&gt;.tar.gz
 463  </blockquote>
 464  
 465  <h3>Descriptions</h3>
 466  <dl>
 467  <dt>&lt;plugin name&gt;:</dt><dd>this is one of the single most important
 468     values you  will choose for your plugin as it dictates the following:
 469        <ul>
 470          <li>The exact API function names that the Geeklog code will try to
 471     call for your plugin</li>
 472          <li>The exact directory within the webtree to put all your plugin
 473      code</li>
 474          <li>The exact directory within the admin directory to put your admin
 475      code</li>
 476          <li>If using moderation, the exact table name main table being moderated</li>
 477          <li>If using moderation, the submission table will be &lt;plugin
 478   name&gt;submission</li>
 479        </ul></dd>
 480  
 481  <dt>&lt;plugin version&gt;:</dt><dd>used during the installation process
 482     to determine  if you are attempting to upgrade a plugin or do a new installation.
 483     It is  also checked to verify that you aren't trying to install and old
 484  version    of  the plugin when a new installation already exists.</dd>
 485  <dt>&lt;geeklog version&gt;:</dt><dd>this is the Geeklog version the plugin
 486    works under.</dd>
 487  </dl>
 488  
 489  <p>The organization of your tarfile is standardized as well.&nbsp; For each
 490  directory and file a description is given.&nbsp; Your base plugin directory
 491  when you create the tarfile should be &lt;plugin name&gt;.&nbsp; Under
 492  there   you will have the following:
 493  
 494  <dl>
 495  <dt>config.php:</dt><dd>configuration page for your plugin.&nbsp; We'd
 496     prefer you to  data-drive most the values if possible but using config.php
 497     is fine.&nbsp;  This file can be called whatever you want...you are not
 498   restricted.</dd>
 499  <dt>functions.inc:</dt><dd>this is the file where you implement the Geeklog
 500     API and where your plugin code should reside.&nbsp; It MUST be named this
 501     because we automatically include all enabled plugins function.inc files
 502   at  the bottom of lib-common.php.&nbsp; Note that this means you have access
 503  to all  the functions in lib-common.php in your plugin code.</dd>
 504  <dt>lang.php or language/ directory:</dt><dd>the language file(s) for your
 505     plugin.&nbsp; You should include this file in your functions.inc.<br>We
 506     recommend that you use a language directory and have a seperate language
 507     file for each supported language (english.php, etc.), mirroring Geeklog's
 508     behaviour and selecting the language file based on the user's preferred
 509     language (falling back to english.php if you can't find a language file for
 510     the selected language).</dd>
 511  
 512  <dt>README</dt><dd>standard readme for software</dd>
 513  <dt>/docs:</dt><dd>includes any documentation you may want to provide
 514    for your plugin  such as history, to-do, etc</dd>
 515  <dt>/admin:</dt><dd>includes only your admininstation pages</dd>
 516  <dt>/public_html:</dt><dd>include your regular web pages</dd>
 517  <dt>/updates:</dt><dd>includes all update sql and scripts</dd>
 518  </dl>
 519  
 520  <h2><a name="How_Geeklog_Installs_Plugins">How To Install A Geeklog Plugin</a></h2>
 521  
 522  <p><strong>Note:</strong> Up until Geeklog version 1.3.4, there was an
 523  automatic install procedure for plugins. This, however, caused too many
 524  problems and support issues and has been removed from later versions. The
 525  manual install as outlined below is now the recommended way to install a
 526  plugin and should work for both old and new versions of Geeklog.
 527  
 528  <p>For details, you should always refer to the README that comes with the
 529  plugin. A general overview of plugins and install details is also provided as part of the Geeklog Documentation Project <a href="http://wiki.geeklog.net/index.php/Plugins">here</a> . In general, however, a plugin will be installed like this:
 530  
 531  <ol>
 532  <li>Depending on your setup and server access, you should either upload
 533    the tarball and unpack it remotely or unpack the tarball locally and
 534    upload the extracted files and folders afterwards.</li>
 535  <li>The public_html directory in the tarfile is copied to the webtree
 536    under &lt;plugin name&gt;. e.g. if my geeklog web is in /path/to/geeklog/public_html/
 537    then the public_html from the tarfile is copied to /path/to/geeklog/public_html/&lt;plugin
 538    name&gt;</li>
 539  <li>The admin directory in the tarfile is copied to the admin webtree.&nbsp;
 540    e.g. if my geeklog admin webtree is in /path/to/geeklog/public_html/admin/
 541    then the admin directory from the tarfile is copied to /path/to/geeklog/public_html/admin/plugins/&lt;plugin
 542    name&gt;&nbsp; </li>
 543  <li>Call the plugins install script at
 544  http://yourgeeklogsite/admin/plugins/&lt;plugin name&gt;/install.php
 545    <ul>
 546    <li>If this is a new install (plugin doesn't exist in plugins table)
 547      then the install script should execute the needed install SQL to create the required tables and default data</li>
 548    <li>If this is an upgrade, you will need to refer to the provided plugin documentation. Newer plugin may support the Plugin API to perform an update. The plugin Editor has the ability for the site admin to execute the update function if available.</li>
 549    </ul></li>
 550  <li>That's it!</li>
 551  </ol>
 552  
 553  <h2><a name="Deliver_Your_Plugin">Deliver Your Plugin!</a></h2>
 554  
 555  <p>Because Geeklog Plugins can affect a Geeklog installation and the users
 556  filesystem, our policy is we will not endorse third party plugins unless
 557  they have been tested by the Geeklog Development team.&nbsp; Why?&nbsp; We
 558  will make sure that your plugin installs successfully and doesn't have any
 559  adverse behavior.&nbsp; Assuming your plugin checks out, we will put your
 560  tarfile on our site where it can be downloaded by Geeklog users.&nbsp; You
 561  can sumbit your plugin to our site at http://www.geeklog.net/</p>
 562  
 563  <table border="0" width="100%" class="footer">
 564  <tr valign="top">
 565    <td colspan="2"><a href="http://wiki.geeklog.net/">The Geeklog Documentation Project</a><br>
 566      All trademarks and copyrights on this page are owned by their respective owners. GeekLog is copyleft.</td>
 567  </tr>
 568  </table>
 569  
 570  </body>
 571  </html>