Difference between revisions of "How to get Started: A Development Overview"

Latest revision as of 19:37, 23 May 2009

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 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.

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 functions.inc:

$_CT_table_prefix='ct_';
$_TABLES['mytable']    = $_CT_table_prefix . 'mytable';
$_TABLES['my2ndtable'] = $_CT_table_prefix . 'my2ndtable';

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 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.
  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.
• A config.php or a 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 English language file

Actually, you can get away with less than that. See Minimal Plugin.

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.

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 plugin_user_delete_{plugin-name} API function. It is being called with the user's ID ($uid) 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.

Likewise, there is also a plugin_user_create_{plugin-name} 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.

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 Geeklog Site admin can create a 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.
• 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.