How to get Started: A Development Overview - Revision history

Dirk: added link to Plugin API

2009-05-23T19:37:37Z

added link to Plugin API

Dirk: PLG_deleteUser / PLG_createUser exist

2009-05-23T14:46:36Z

PLG_deleteUser / PLG_createUser exist

Dirk: minor updates / corrections

2009-05-23T14:38:50Z

minor updates / corrections

Dirk: a few links and minor corrections

2009-05-21T17:34:27Z

a few links and minor corrections

Dirk: missing category

2009-05-21T17:21:50Z

missing category

Dirk: Changed category

2008-05-10T20:14:15Z

Changed category

Tomw at 13:56, 1 July 2004

2004-07-01T13:56:32Z

Tomw at 21:18, 28 June 2004

2004-06-28T21:18:08Z

New page

There are two important decisions that you should make before you begin development of either your block or your plugin.

1) Naming: You need to decide on a name by which your block or plugin will be referred to in your code. For a block this is not as important as it is for a plugin, unless the block consists of several functions and/or has global configuration variables. See Naming Convention in the coding style section. For a plugin a single word name is required. It becomes the name of the sub-directories in which the plugin is installed and is used by the plugin API to interact with the plugin. Throughout this documentation you will find references to {plugin-name}. The value of {plugin-name} is the name you choose here.

2) DB Table Names: It is good practice to implement a prefix system for all your database tables like Geeklog has. This allows a site operator to run multiple sites off of the same database. You can add your tables to the $_TABLES array if you want and either use the global $_DB_table_prefix or better yet create your own prefix to prevent naming collisions. To include your tables in the $_TABLES variable, include lines like these at the top of your function.inc:

<pre>
$_CT_table_prefix='ct_';
$_TABLES['mytable'] = $_CT_table_prefix . 'mytable';
$_TABLES['my2ndtable'] = $_CT_table_prefix . 'my2ndtable';
</pre>

== Plugin minimum requirements ==

It is possible to create a plugin with only a few files and using the universal installer program and sample functions, this a should be a very easy project and a good place for plugin developers to start and get familiar. The minimum that your plugin project will require is the following:

*Install.php - which will be executed from public_html/admin/plugins/myplugin/install.php. You would use the universal installer and follow the directions in this developer's guide.
*functions.inc - which contains the plugin functions and is automatically included by Geeklog from lib-common.php for all enabled plugins. Only the uninstall function would need to be defined. This is called from the plugin install.php and it is assumed to exist. Also the plugin editor wants to call the uninstall function if you use the delete.
*A config.php which defines any plugin tables or config variables that need to be made global. If there are none - this is even optional.
*The include or reference to the plugin config.php is done from functions.inc
*The English language file

== User Definable Preferences ==

If your project has the capability for the user to define individual preferences or settings, you do not want to extend or modify the core Geeklog tables to store these values. It may appear to be the easiest method but it is highly discouraged. You will want to add a project specific table such as 'cb_userprefs' for the Chatterblock plugin. Keeping your project tables separate allow the core tables to be maintained without breaking contributed code.

Your project usersettings program will then need to check if a record already exists for this user and if not create one. In your main project code, you would check if the current user has a record for their preferences and if not - use the site defaults. You can create a record with the user id of 0 for the site defaults.

You will find example code for this method in the Chatterblock Plugin - the program cb_userprefs.php.

The one problem with this method is that there is no way to delete the user settings records should the user be deleted. Users are not normally deleted (which is not a good excuse) but there is no user admin API to hook into currently.

Discussions are underway to include additional API's in GL release 1.3.8 to support calling Plugin User admin functions when new uses are added, edited or removed.

== A few other best practices ==

*All but the simplest of projects should include a help file. This should be an HTML formatted file with which the GL Site admin can create a staticpage and reference in the help url for the block.
*Blocks that contain more than roughly 25 lines of code and possibly multiple functions should be written to reference include files to keep the lib-custom.php file more readable.
*The include file and any other files the block uses should be placed in a public_html/{blockname} directory.
*If you need to access Geekog globals or functions use the require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.
*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.

@@ Line 1: / Line 1: @@
 There are two important decisions that you should make before you begin development of either your block or your plugin.
-) Naming: You need to decide on a name by which your block or plugin will be referred to in your code. For a block this is not as important as it is for a plugin, unless the block consists of several functions and/or has global configuration variables. See [[Programming Style#Naming_Convention|Naming Convention]] in the [[Programming Style]] section. For a plugin a single word name is required. It becomes the name of the sub-directories in which the plugin is installed and is used by the plugin API to interact with the plugin. Throughout this documentation you will find references to {plugin-name}. The value of {plugin-name} is the name you choose here.
+) Naming: You need to decide on a name by which your block or plugin will be referred to in your code. For a block this is not as important as it is for a plugin, unless the block consists of several functions and/or has global configuration variables. See [[Programming Style#Naming_Convention|Naming Convention]] in the [[Programming Style]] section. For a plugin a single word name is required. It becomes the name of the sub-directories in which the plugin is installed and is used by the [[Plugin API]] to interact with the plugin. Throughout this documentation you will find references to {plugin-name}. The value of {plugin-name} is the name you choose here.
 ) DB Table Names: It is good practice to implement a prefix system for all your database tables like Geeklog has. This allows a site operator to run multiple sites off of the same database. You can add your tables to the $_TABLES array if you want and either use the global $_DB_table_prefix or better yet create your own prefix to prevent naming collisions. To include your tables in the $_TABLES variable, include lines like these at the top of your functions.inc:

@@ Line 33: / Line 33: @@
 You will find example code for this method in the [[Chatterblock Plugin]] - the program <tt>cb_userprefs.php</tt>.
-The one problem with this method is that there is no way to delete the user settings records should the user be deleted. Users are not normally deleted (which is not a good excuse) but there is no user admin API to hook into currently.
+If you do this, you will need to keep track of user accounts that are deleted so that you can remove the user-specific information from your plugin's tables. To do this, implement the <code>plugin_user_delete_{plugin-name}</code> API function. It is being called with the user's ID (<code>$uid</code>) when Geeklog is about to delete that user account, i.e. the user's data is still intact and will only be removed upon return from your API function.
-Discussions are underway to include additional API's in Geeklog release 1.3.8 to support calling Plugin User admin functions when new users are added, edited or removed.
+Likewise, there is also a <code>plugin_user_create_{plugin-name}</code> API function that is being called when a new user account is created, in case you want to set up some default data for the new user in your plugin's tables.

@@ Line 16: / Line 16: @@
 It is possible to create a plugin with only a few files and using the universal installer program and sample functions. This should be a very easy project and a good place for plugin developers to start and get familiar. The minimum that your plugin project will require is the following:
-* Install.php - which will be executed from public_html/admin/plugins/myplugin/install.php. You would use the universal installer and follow the directions in this developer's guide.<br/>As of Geeklog 1.6.0 most of the installation code can be left to Geeklog, see [[Plugin Autoinstall]].
+* <tt>install.php</tt> - which will be executed from public_html/admin/plugins/myplugin/install.php. You would use the universal installer and follow the directions in this developer's guide.<br/>As of Geeklog 1.6.0 most of the installation code can be left to Geeklog, see [[Plugin Autoinstall]].
-* functions.inc - which contains the plugin functions and is automatically included by Geeklog from lib-common.php for all enabled plugins. Only the uninstall function would need to be defined. This is called from the plugin install.php and it is assumed to exist. Also the plugin editor wants to call the uninstall function if you use the delete.
+* <tt>functions.inc</tt> - which contains the plugin functions and is automatically included by Geeklog from <tt>lib-common.php</tt> for all enabled plugins. Only the uninstall function would need to be defined. This is called from the plugin <tt>install.php</tt> and it is assumed to exist. Also the plugin editor wants to call the uninstall function if you use the delete.
-* A config.php which defines any plugin tables or config variables that need to be made global. If there are none - this is even optional.
+* A <tt>config.php</tt> or a [[PluginConfiguration|plugin-specific section]] in the Configuration, which defines any plugin tables or config variables that need to be made global. If there are none - this is even optional.
-* The include or reference to the plugin config.php is done from functions.inc
+* The include or reference to the plugin <tt>config.php</tt> is done from <tt>functions.inc</tt>
 * The English language file
@@ Line 27: / Line 27: @@
 == User Definable Preferences ==
-If your project has the capability for the user to define individual preferences or settings, you do not want to extend or modify the core Geeklog tables to store these values. It may appear to be the easiest method but it is highly discouraged. You will want to add a project specific table such as 'cb_userprefs' for the Chatterblock plugin. Keeping your project tables separate allow the core tables to be maintained without breaking contributed code.
+If your project has the capability for the user to define individual preferences or settings, you do not want to extend or modify the core Geeklog tables to store these values. It may appear to be the easiest method but it is highly discouraged. You will want to add a project specific table such as 'cb_userprefs' for the [[Chatterblock Plugin]]. Keeping your project tables separate allow the core tables to be maintained without breaking contributed code.
 Your project usersettings program will then need to check if a record already exists for this user and if not create one. In your main project code, you would check if the current user has a record for their preferences and if not - use the site defaults. You can create a record with the user id of 0 for the site defaults.
-You will find example code for this method in the Chatterblock Plugin - the program cb_userprefs.php.
+You will find example code for this method in the [[Chatterblock Plugin]] - the program <tt>cb_userprefs.php</tt>.
 The one problem with this method is that there is no way to delete the user settings records should the user be deleted. Users are not normally deleted (which is not a good excuse) but there is no user admin API to hook into currently.
@@ Line 41: / Line 41: @@
 * All but the simplest of projects should include a help file. This should be an HTML formatted file with which the Geeklog Site admin can create a [[Static Pages Plugin|static page]] and reference in the help url for the block.
-* Blocks that contain more than roughly 25 lines of code and possibly multiple functions should be written to reference include files to keep the lib-custom.php file more readable.
+* Blocks that contain more than roughly 25 lines of code and possibly multiple functions should be written to reference include files to keep the <tt>lib-custom.php</tt> file more readable.
-* The include file and any other files the block uses should be placed in a public_html/{blockname} directory.
+* The include file and any other files the block uses should be placed in a <tt>public_html/{blockname}</tt> directory.
-* If you need to access Geekog globals or functions use the require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.
+* If you need to access Geekog globals or functions use the <code>require_once</code> of <tt>lib-common.php</tt> at the top of your external program files. You will need to do this to access <code>$_CONF</code> or any other global variable.
-* Example: <pre>require_once '../lib-common.php';</pre> is the standard way this is done and assumes your project files are under public_html.
+* Example: <pre>require_once '../lib-common.php';</pre> is the standard way this is done and assumes your project files are under <tt>public_html</tt>.
 [[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

← Older revision		Revision as of 17:21, 21 May 2009
Line 46:		Line 46:
	*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.		*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.

−	[[Category:Plugin Development]]	+
		+	[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

← Older revision		Revision as of 20:14, 10 May 2008
Line 46:		Line 46:
	*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.		*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.

−	[[Category:~~Plugin_Developers_Handbook~~]]	+	[[Category:Plugin Development]]

@@ Line 1: / Line 1: @@
 There are two important decisions that you should make before you begin development of either your block or your plugin.
-) Naming: You need to decide on a name by which your block or plugin will be referred to in your code. For a block this is not as important as it is for a plugin, unless the block consists of several functions and/or has global configuration variables. See Naming Convention in the coding style section. For a plugin a single word name is required. It becomes the name of the sub-directories in which the plugin is installed and is used by the plugin API to interact with the plugin. Throughout this documentation you will find references to {plugin-name}. The value of {plugin-name} is the name you choose here.
+) Naming: You need to decide on a name by which your block or plugin will be referred to in your code. For a block this is not as important as it is for a plugin, unless the block consists of several functions and/or has global configuration variables. See [[Programming Style#Naming_Convention|Naming Convention]] in the [[Programming Style]] section. For a plugin a single word name is required. It becomes the name of the sub-directories in which the plugin is installed and is used by the plugin API to interact with the plugin. Throughout this documentation you will find references to {plugin-name}. The value of {plugin-name} is the name you choose here.
-) DB Table Names: It is good practice to implement a prefix system for all your database tables like Geeklog has. This allows a site operator to run multiple sites off of the same database. You can add your tables to the $_TABLES array if you want and either use the global $_DB_table_prefix or better yet create your own prefix to prevent naming collisions. To include your tables in the $_TABLES variable, include lines like these at the top of your function.inc:
+) DB Table Names: It is good practice to implement a prefix system for all your database tables like Geeklog has. This allows a site operator to run multiple sites off of the same database. You can add your tables to the $_TABLES array if you want and either use the global $_DB_table_prefix or better yet create your own prefix to prevent naming collisions. To include your tables in the $_TABLES variable, include lines like these at the top of your functions.inc:
 <pre>
@@ Line 10: / Line 10: @@
 $_TABLES['my2ndtable'] = $_CT_table_prefix . 'my2ndtable';
 </pre>
 == Plugin minimum requirements ==
-It is possible to create a plugin with only a few files and using the universal installer program and sample functions, this a should be a very easy project and a good place for plugin developers to start and get familiar. The minimum that your plugin project will require is the following:
+It is possible to create a plugin with only a few files and using the universal installer program and sample functions. This should be a very easy project and a good place for plugin developers to start and get familiar. The minimum that your plugin project will require is the following:
-*Install.php - which will be executed from public_html/admin/plugins/myplugin/install.php. You would use the universal installer and follow the directions in this developer's guide.
+* Install.php - which will be executed from public_html/admin/plugins/myplugin/install.php. You would use the universal installer and follow the directions in this developer's guide.<br/>As of Geeklog 1.6.0 most of the installation code can be left to Geeklog, see [[Plugin Autoinstall]].
-*functions.inc - which contains the plugin functions and is automatically included by Geeklog from lib-common.php for all enabled plugins. Only the uninstall function would need to be defined. This is called from the plugin install.php and it is assumed to exist. Also the plugin editor wants to call the uninstall function if you use the delete.
+* functions.inc - which contains the plugin functions and is automatically included by Geeklog from lib-common.php for all enabled plugins. Only the uninstall function would need to be defined. This is called from the plugin install.php and it is assumed to exist. Also the plugin editor wants to call the uninstall function if you use the delete.
-*A config.php which defines any plugin tables or config variables that need to be made global. If there are none - this is even optional.
+* A config.php which defines any plugin tables or config variables that need to be made global. If there are none - this is even optional.
-*The include or reference to the plugin config.php is done from functions.inc
+* The include or reference to the plugin config.php is done from functions.inc
-*The English language file
+* The English language file
-−
@@ Line 33: / Line 35: @@
 The one problem with this method is that there is no way to delete the user settings records should the user be deleted. Users are not normally deleted (which is not a good excuse) but there is no user admin API to hook into currently.
-Discussions are underway to include additional API's in GL release 1.3.8 to support calling Plugin User admin functions when new uses are added, edited or removed.
+Discussions are underway to include additional API's in Geeklog release 1.3.8 to support calling Plugin User admin functions when new users are added, edited or removed.
 == A few other best practices ==
-*All but the simplest of projects should include a help file. This should be an HTML formatted file with which the GL Site admin can create a staticpage and reference in the help url for the block.
+* All but the simplest of projects should include a help file. This should be an HTML formatted file with which the Geeklog Site admin can create a [[Static Pages Plugin|static page]] and reference in the help url for the block.
-*Blocks that contain more than roughly 25 lines of code and possibly multiple functions should be written to reference include files to keep the lib-custom.php file more readable.
+* Blocks that contain more than roughly 25 lines of code and possibly multiple functions should be written to reference include files to keep the lib-custom.php file more readable.
-*The include file and any other files the block uses should be placed in a public_html/{blockname} directory.
+* The include file and any other files the block uses should be placed in a public_html/{blockname} directory.
-*If you need to access Geekog globals or functions use the  require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.
+* If you need to access Geekog globals or functions use the require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.
-*Example: require_once("../lib-common.php")     is the standard way this is done and assumes your project files are under public_html.
+* Example: <pre>require_once '../lib-common.php';</pre> is the standard way this is done and assumes your project files are under public_html.
 [[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

← Older revision		Revision as of 13:56, 1 July 2004
Line 45:		Line 45:
	*If you need to access Geekog globals or functions use the require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.		*If you need to access Geekog globals or functions use the require_once of lib-common.php at the top of your external program files. You will need to do this to access $_CONF or any other global variable.
	*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.		*Example: require_once("../lib-common.php") is the standard way this is done and assumes your project files are under public_html.
		+
		+	[[Category:Plugin_Developers_Handbook]]