Difference between revisions of "Blocks and Plugins"

Latest revision as of 19:36, 23 May 2009

There are two different kinds of enhancements to Geeklog. The difference between them lies both in the area they are displayed and in the way you integrate them with Geeklog. This is not a strict definition or listing of the features and differences but one that has been evolving. A plugin is really an addon that uses the Plugin API while a block is code added to lib-custom.php and is then defined by the plugin editor. But what are the other differences and why as a developer would I create one vs. the other is a good question and one I hope to answer in this section.

If you are new to Geeklog, we suggest you start with a block. This will get you familiar with the Geeklog way of doing things.

Definitions

There are three block types:

We are really focused on the third type - PHP blocks - and not the other two when we reference the block definition in this guide. The following defining attributes are a guide as there is no necessarily right or wrong way to release your project but these are meant to guide you.

Blocks

• The block facility in Geeklog allows for blocks to call PHP functions that start with 'phpblock_'.
• The 'phpblock_' function must return correct HTML which will then be displayed in one of the blocks in either the left or right column.
• May be very basic PHP code to execute a query to return a list of the last 10 comments, links, plugin records and return the formatted results
• May be a complete program with several features and 100's of lines of code. Eventually the block may start to contain enough logic and features that it should be a plugin.
• Blocks are often small PHP routines like a Theme Changer or display some specific information like Random Quotes in a side block
• Many blocks do not have any database or tables
• Can be distributed as a single file containing the code to insert into lib-custom.php and instructions or contain several files which are placed in a directory under public_html
• There are many examples of blocks so we encourage you to download them, install them and explore their code to gain more understanding

Plugins

• Use the Plugin API calls
• May be just a basic addon with PHP code but are normally more advanced.
• Could be just a way of auto installing a block with no admin, user, search or comment features
• Require as a minimum the following four files: config.php (or a file to initialize the configuration in the database), functions.inc with only the uninstall function defined, language file and install.php (also see Minimal Plugin)
• Usually have at least one new table
• Integrate core Geeklog functionality and features
• Good way to integrate a separate S/W solution and integrate the installation for easier distribution

Why a plugin

There are several blocks that can be personalized or have user settings. There are several classic ones (Stock and Weather) as an example that have extended user preferences. There is no right or wrong way but the following list outlines some of the reasons you may want to develop a plugin vs. a block or convert a block to a plugin.

• If the addon has a user preferences or an an admin component. The description and links can be automatically added to their related menus for the user.
• With a plugin, users don't have to modify lib-custom.php. They are automatically included as they are referenced in the plugin's function.inc files. The plugin's function.inc file can also include the phpblock function if the addon has a block feature.
• Users do not have to manually create tables or run a SQL script. The plugin install program will have the SQL to create the new tables.
• The addon can check for the user's language setup and if there is a corresponding plugin language file. If this is done in functions.inc or the config.php, the variables will be created as globals and allow you to easily reference then in your addon.
• Extend your project to utilize some of the Plugin API's and integrate Geeklog core features:
  • Extend the Geeklog search to include your plugin results
  • Add your project to the site stats listing. Very easy to include the number of records in your plugin to the Site Statistics and you can optionally add a more detailed stats function
  • Enable your addon to use the comment engine and allow comments
  • Enable moderation so that new plugin items to be approved before posting to the site
• The auto install and uninstall is one of the most important benefits. Once the site admin understands how to copy the plugin distribution files to the public_html and admin directories, the install is all online with no file editing. The install script includes error or status logging which helps in troubleshooting. If there is an install error, the installer removes everything.
• Automatically add a link under the site header to your plugin feature. All templates reference a variable {plg_menu_elements} in the header.thtml files. This variable is defined by making a call to all plugins and if the function getmenuitems exists, it can return the link and description to be displayed.
• The install program creates any addon security groups and access rights automatically. It can create the block definition as well so the user does not even have to use the block editor.
• Once you have a working project, it should only take a few more hours to make it a working plugin.