Difference between revisions of "Blocks and Plugins"

From GeeklogWiki
Jump to: navigation, search
(=Plugins:=)
m (added links to Plugin API)
 
(7 intermediate revisions by 2 users not shown)
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.
 
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 11: Line 11:
 
   <tr>
 
   <tr>
 
     <td width="20%"><b><font size="2"><i>Normal Block</i></font></b></td>
 
     <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>
    only program. The block content is entered in the block editor.</font></td>
 
 
   </tr>
 
   </tr>
 
   <tr>
 
   <tr>
 
     <td width="20%"><b><i><font size="2">Portal Block</font></i></b></td>
 
     <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>
    RDF source is entered in the block editor</font></td>
 
 
   </tr>
 
   </tr>
 
   <tr>
 
   <tr>
 
     <td width="20%"><b><i><font size="2">PHP Block</font></i></b></td>
 
     <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  
+
     <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>
    code is a function whose name must begin with phpblock_ Example:  
 
    phpblock_myblock</font></td>
 
 
   </tr>
 
   </tr>
 
</table>
 
</table>
Line 29: Line 25:
 
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.
 
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: ===
 
  
 +
=== 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
+
* 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: ===
+
=== 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: <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
 +
* Good way to integrate a separate S/W solution and integrate the installation for easier distribution
  
*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, functions.inc with only the uninstall function defined, language file and install.php
 
*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 ==
 
== 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 table outlines some of the reasons you may want to develop a plugin vs. a block or convert a block to 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.   
+
* 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 [[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
 +
** Enable your addon to use the [[Integrating the Comment Engine|comment engine]] and allow comments
 +
** 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.
 +
* 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.
  
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
+
[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]
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 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.
 
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.
 
 
 
[[Category:Plugin_Developers_Handbook]]
 

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:

Normal Block Used to just display HTML or a JavaScript only program. The block content is entered in the block editor.
Portal Block Used to import and display a RSS or Atom news feed. The RSS URL is entered in the block editor
PHP Block Reference a custom PHP coded block. The block code is a function whose name must begin with phpblock_
Example: phpblock_myblock

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.