Difference between revisions of "Preparing your Geeklog Plugin Distribution"

From GeeklogWiki
Jump to: navigation, search
(An attempt to update this information)
 
(3 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
All Geeklog plugin tarfiles should use the following naming convention:  
 
All Geeklog plugin tarfiles should use the following naming convention:  
  
<plugin name>_<plugin version>_<geeklog version>.tar.gz  
+
<pre><plugin name>_<plugin version>_<geeklog version>.tar.gz</pre>
 +
 
 +
For example: <tt>photos_1.0_1.5.2.tar.gz</tt>
  
 
== Descriptions ==
 
== Descriptions ==
Line 9: Line 11:
 
'''<plugin name>:'''<br/>
 
'''<plugin name>:'''<br/>
 
this is one of the single most important values you will choose for your plugin as it dictates the following:  
 
this is one of the single most important values you will choose for your plugin as it dictates the following:  
*The exact API function names that the Geeklog code will try to call for your plugin  
+
* The exact API function names that the Geeklog code will try to call for your plugin  
*The exact directory within the webtree to put all your plugin code  
+
* The exact directory within the webtree to put all your plugin code  
*The exact directory within the admin directory to put your admin code  
+
* The exact directory within the admin directory to put your admin code  
*If using moderation, the exact table name main table being moderated  
+
* If using moderation, the exact table name and main table being moderated  
*If using moderation, the submission table will be <plugin name>submission  
+
* If using moderation, the submission table will be <tt><plugin name>submission</tt>
  
 
'''<plugin version>:'''<br/>
 
'''<plugin version>:'''<br/>
Line 21: Line 23:
 
this is the Geeklog version the plugin works under.  
 
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:  
+
== Files and Directories ==
 +
 
 +
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 <tt><plugin name></tt>.  Under there you will have the following:  
  
 
'''config.php''':<br/>
 
'''config.php''':<br/>
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.  
+
traditional configuration file for your plugin. We'd prefer that new plugins use the [[PluginConfiguration|Configuration GUI]] if possible but using <tt>config.php</tt> is fine.
  
 
'''functions.inc''':<br/>
 
'''functions.inc''':<br/>
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 lib-common.php. Note that this means you have access to all the functions in lib-common.php in your plugin code.
+
this is the file where you implement the Geeklog [[Plugin API]] and where your plugin code should reside.  It '''must''' be named this because we automatically include the <tt>function.inc</tt> files of all enabled plugins at the bottom of <tt>lib-common.php</tt>. Note that this means you have access to all the functions in <tt>lib-common.php</tt> in your plugin code.  
 
 
'''lang.php or language/ directory''':<br/>
 
the language file(s) for your plugin.  You should include this file in your functions.inc.
 
We recommend that you use a language directory and have a seperate language file for each supported language (english.php, etc.), mirroring Geeklog's behaviour and selecting the language file based on the user's preferred language (falling back to english.php if you can't find a language file for the selected language).
 
 
 
'''table.sql'''<br/>
 
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 your 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'''<br/>
 
sample data for your plugin
 
  
 
'''README'''<br/>
 
'''README'''<br/>
Line 49: Line 40:
  
 
'''/admin:'''<br/>
 
'''/admin:'''<br/>
includes only your admininstation pages  
+
includes only your admininstration pages  
 +
 
 +
'''/language:'''<br/>
 +
the language files for your plugin.
 +
We recommend that you use a language directory and have a separate language file for each supported language (<tt>english.php</tt>, etc.), mirroring Geeklog's behaviour and selecting the language file based on the user's preferred language (falling back to <tt>english.php</tt> if you can't find a language file for the selected language).
  
 
'''/public_html:'''<br/>
 
'''/public_html:'''<br/>
include your regular web pages  
+
includes your regular web pages  
 +
 
 +
'''/sql:'''<br/>
 +
table definitions for each supported DBMS
 +
 
  
'''/updates:'''<br/>
+
[[Category:Plugin Development]]
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.
 

Latest revision as of 12:55, 4 June 2009

The plugin tarfile

All Geeklog plugin tarfiles should use the following naming convention:

<plugin name>_<plugin version>_<geeklog version>.tar.gz

For example: photos_1.0_1.5.2.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:

  • The exact API function names that the Geeklog code will try to call for your plugin
  • The exact directory within the webtree to put all your plugin code
  • The exact directory within the admin directory to put your admin code
  • If using moderation, the exact table name and main table being moderated
  • If using moderation, the submission table will be <plugin name>submission

<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 checked to verify that you aren't trying to install and old version of the plugin when a new installation already exists.

<geeklog version>:
this is the Geeklog version the plugin works under.

Files and Directories

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:
traditional configuration file for your plugin. We'd prefer that new plugins use the Configuration GUI if possible but using config.php is fine.

functions.inc:
this is the file where you implement the Geeklog Plugin API and where your plugin code should reside. It must be named this because we automatically include the function.inc files of all enabled plugins at the bottom of lib-common.php. Note that this means you have access to all the functions in lib-common.php in your plugin code.

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 admininstration pages

/language:
the language files for your plugin. We recommend that you use a language directory and have a separate language file for each supported language (english.php, etc.), mirroring Geeklog's behaviour and selecting the language file based on the user's preferred language (falling back to english.php if you can't find a language file for the selected language).

/public_html:
includes your regular web pages

/sql:
table definitions for each supported DBMS