Blocks and Plugins - Revision history

Dirk: added links to Plugin API

2009-05-23T19:36:46Z

added links to Plugin API

Dirk: more links

2009-05-23T14:30:16Z

Dirk: Minor corrections

2009-05-23T14:12:39Z

Minor corrections

Dirk: a few links and minor corrections

2009-05-21T17:59:43Z

a few links and minor corrections

Dirk: cosmetics and some minor additions/corrections

2009-05-04T14:33:05Z

cosmetics and some minor additions/corrections

Dirk: Changed category

2008-05-10T20:13:53Z

Changed category

Dirk: Fixed formatting

2007-07-07T14:19:49Z

Fixed formatting

Tomw: =Why a plugin=

2004-06-28T21:15:29Z

=Why a plugin=

Tomw: =Plugins:=

2004-06-28T21:13:34Z

=Plugins:=

Tomw: =Definitions=

2004-06-28T21:13:06Z

=Definitions=

@@ Line 1: / Line 1: @@
-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 [[Blocks|block]] is code added to <tt>lib-custom.php</tt> 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.
+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 [[Blocks|block]] is code added to <tt>lib-custom.php</tt> 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.
@@ Line 40: / Line 40: @@
 === Plugins ===
-* Use the Plugin API calls
+* 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
@@ Line 57: / Line 57: @@
 * 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 your project to utilize some of the [[Plugin API]]'s and integrate Geeklog core features:
 ** Extend the Geeklog [[Using Geeklog's Improved Search Engine|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 [[Extending Site Statistics with your plugin|Site Statistics]] and you can optionally add a more detailed stats function

@@ Line 59: / Line 59: @@
 * Extend your project to utilize some of the Plugin API's and integrate Geeklog core features:
 ** Extend the Geeklog [[Using Geeklog's Improved Search Engine|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
+** Add your project to the site stats listing. Very easy to include the number of records in your plugin to the [[Extending Site Statistics with your plugin|Site Statistics]] and you can optionally add a more detailed stats function
-** Enable your addon to use the comment engine and allow comments
+** Enable your addon to use the [[Integrating the Comment Engine|comment engine]] and allow comments
-** Enable moderation so that new plugin items to be approved before posting to the site
+** Enable [[Adding Moderation Capability|moderation]] so that new plugin items to be approved before posting to the site
 * The [[Plugin Autoinstall|auto install]] and [[Plugin Auto-Uninstall|uninstall]] is one of the most important benefits. Once the site admin understands how to copy the plugin distribution files to the <tt>public_html</tt> and <tt>admin</tt> 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 <code>{plg_menu_elements}</code> in the <tt>header.thtml</tt> files. This variable is defined by making a call to all plugins and if the function <code>getmenuitems</code> exists, it can return the link and description to be displayed.

@@ Line 11: / Line 11: @@
    <tr>
      <td width="20%"><b><font size="2"><i>Normal Block</i></font></b></td>
-     <td width="80%"><font size="2">Used to just display HTML or a Javascript
+     <td width="80%"><font size="2">Used to just display HTML or a JavaScript only program. The block content is entered in the block editor.</font></td>
    </tr>
    <tr>
      <td width="20%"><b><i><font size="2">Portal Block</font></i></b></td>
-     <td width="80%"><font size="2">Used to define a RDF or RSS news feed. The
+     <td width="80%"><font size="2">Used to import and display a RSS or Atom news feed. The RSS URL is entered in the block editor</font></td>
    </tr>
    <tr>
      <td width="20%"><b><i><font size="2">PHP Block</font></i></b></td>
-     <td width="80%"><font size="2">Reference a custom PHP coded block. The block code is a function whose name must begin with <code>phpblock_</code><br>Example: <code>phpblock_myblock</code></font></td>
+     <td width="80%"><font size="2">Reference a custom PHP coded block. The block code is a function whose name must begin with <code>phpblock_</code><br/>Example: <code>phpblock_myblock</code></font></td>
    </tr>
 </table>
@@ Line 30: / Line 28: @@
 === Blocks ===
-* The block facility in Geeklog allows for blocks to call php functions that start with 'phpblock_'.
+* The block facility in Geeklog allows for blocks to call PHP functions that start with '<code>phpblock_</code>'.
-* The 'phpblock_' function must return correct HTML which will then be displayed in one of the blocks in either the left or right column.
+* The '<code>phpblock_</code>' 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 executes a query to return a list of the last 10 comments, links, plugin records and return the formatted results
+* 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 complete programs 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.
+* 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 Theme Changer or display some specific information like Random Quotes in a site block
+* 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 <tt>lib-custom.php</tt> and instructions or contain several files which are placed in a directory under <tt>public_html</tt>

@@ Line 1: / Line 1: @@
-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 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.
+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 [[Blocks|block]] is code added to <tt>lib-custom.php</tt> 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.
@@ Line 34: / Line 34: @@
 * May be very basic PHP code to executes a query to return a list of the last 10 comments, links, plugin records and return the formatted results
 * May be complete programs 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 Theme Changer or display some specific information like Random Quotes in a site block
+* Blocks are often small PHP routines like Theme Changer or display some specific information like Random Quotes in a site block
 * Many blocks do not have any database or tables
 * Can be distributed as a single file containing the code to insert into <tt>lib-custom.php</tt> and instructions or contain several files which are placed in a directory under <tt>public_html</tt>
@@ Line 45: / Line 45: @@
 * 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: <tt>config.php</tt> (or a file to initialize the configuration in the database), <tt>functions.inc</tt> with only the uninstall function defined, language file and </tt>install.php</tt> (also see [[Minimal Plugin]])
+* Require as a minimum the following four files: <tt>config.php</tt> (or a file to initialize the configuration in the database), <tt>functions.inc</tt> with only the uninstall function defined, language file and <tt>install.php</tt> (also see [[Minimal Plugin]])
 * Usually have at least one new table
 * Integrate core Geeklog functionality and features
@@ Line 65: / Line 65: @@
 ** Enable moderation so that new plugin items to be approved before posting to the site
 * The [[Plugin Autoinstall|auto install]] and [[Plugin Auto-Uninstall|uninstall]] is one of the most important benefits. Once the site admin understands how to copy the plugin distribution files to the <tt>public_html</tt> and <tt>admin</tt> 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 <code>{plg_menu_elements}</code> in the <tt>header.thtml</tt> 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.
+* Automatically add a link under the site header to your plugin feature. All templates reference a variable <code>{plg_menu_elements}</code> in the <tt>header.thtml</tt> files. This variable is defined by making a call to all plugins and if the function <code>getmenuitems</code> 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.

@@ Line 30: / Line 30: @@
 === Blocks ===
-*The block facility in Geeklog allows for blocks to call php functions that start with 'phpblock_'.
+* 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.
+* 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 executes a query to return a list of the last 10 comments, links, plugin records and return the formatted results
+* May be very basic PHP code to executes a query to return a list of the last 10 comments, links, plugin records and return the formatted results
-*May be complete programs 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.
+* May be complete programs 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 Theme Changer or display some specific information like Random Quotes in a site block
+* Blocks are often small php routines like Theme Changer or display some specific information like Random Quotes in a site block
-*Many blocks do not have any database or tables
+* Many blocks do not have any database or tables
-*Can be distributed as a single file containing the code to insert into lib-custom and instructions or contain several files which are placed in a directory under public_html
+* Can be distributed as a single file containing the code to insert into <tt>lib-custom.php</tt> and instructions or contain several files which are placed in a directory under <tt>public_html</tt>
-*There are many examples of blocks so we encourage you to download them, install them and explore their code to gain more understanding
+* 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
+* Use the Plugin API calls
-*May be just a basic addon with PHP code but are normally more advanced.
+* 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
+* 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, functions.inc with only the uninstall function defined, language file and install.php
+* Require as a minimum the following four files: <tt>config.php</tt> (or a file to initialize the configuration in the database), <tt>functions.inc</tt> with only the uninstall function defined, language file and </tt>install.php</tt> (also see [[Minimal Plugin]])
-*Usually have at least one new table
+* Usually have at least one new table
-*Integrate core Geeklog functionality and features
+* Integrate core Geeklog functionality and features
-*Good way to integrate a separate S/W solution and integrate the installation for easier distribution
+* Good way to integrate a separate S/W solution and integrate the installation for easier distribution
@@ Line 55: / Line 55: @@
 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.
+* 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 or add table definitions to lib-database. 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.
+* With a plugin, users don't have to modify <tt>lib-custom.php</tt>. They are automatically included as they are referenced in the plugin's <tt>function.inc</tt> files. The plugin's <tt>function.inc</tt> 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.
+* 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.
+* 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 your project to utilize some of the Plugin API's and integrate Geeklog core features:
-**Extend the Geeklog search to include your plugin results
+** Extend the Geeklog [[Using Geeklog's Improved Search Engine|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
+** 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 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
+** Enable moderation so that new plugin items to be approved before posting to the site
-*The auto install and unininstall is one of the most imnportant 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.
+* The [[Plugin Autoinstall|auto install]] and [[Plugin Auto-Uninstall|uninstall]] is one of the most important benefits. Once the site admin understands how to copy the plugin distribution files to the <tt>public_html</tt> and <tt>admin</tt> 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.
+* Automatically add a link under the site header to your plugin feature. All templates reference a variable <code>{plg_menu_elements}</code> in the <tt>header.thtml</tt> 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.
+* 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.
+* Once you have a working project, it should only take a few more hours to make it a working plugin.
 [[Category:Plugin Development]]

← Older revision		Revision as of 20:13, 10 May 2008
Line 69:		Line 69:
	*Once you have a working project, it should only take a few more hours to make it a working plugin.		*Once you have a working project, it should only take a few more hours to make it a working plugin.

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

@@ Line 26: / Line 26: @@
    </tr>
 </table>
 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.