Difference between revisions of "Geeklog's way of doing things"

From GeeklogWiki
Jump to: navigation, search
 
(Commonly used Geeklog functions: added COM_setArgNames and COM_getArgument)
 
(21 intermediate revisions by 6 users not shown)
Line 1: Line 1:
All of Geeklog's php files are pure php. PHP allows you to use php as a scripting language imbedded in html files but this is not how Geeklog does it. All of Geeklog's php files must have <?php as the first five characters and end with ?>. Failure to structure your Geeklog files this way will cause session and header errors. Geeklog attempts as much as possible to have only php code in the php files. Two of the conventions used in Geeklog to accomplish this are the use of templates and language files.
+
All of Geeklog's PHP files are pure PHP. PHP allows you to use PHP as a scripting language embedded in HTML files but this is not how Geeklog does it. All of Geeklog's PHP files must have <?php as the first five characters and end with ?>. Failure to structure your Geeklog files this way will cause session and header errors. Geeklog attempts as much as possible to have only PHP code in the <tt>.php</tt> files. Two of the conventions used in Geeklog to accomplish this are the use of [[Using Templates and Language Files#Templates|templates]] and [[Using Templates and Language Files#Language Files|language files]].
  
 
Time will be well spent by the Geeklog plugin or block developer to become familiar with several Geeklog libraries. The following section outlines the more important or frequently used libraries, functions and standards.  
 
Time will be well spent by the Geeklog plugin or block developer to become familiar with several Geeklog libraries. The following section outlines the more important or frequently used libraries, functions and standards.  
  
  
+
== lib-common.php ==
  
== lib-common.php: ==
+
The Geeklog plugin or block developer should have a good understanding of <tt>lib-common.php</tt> which contains most of the display routines as well as some other general purpose routines. All of the Geeklog display routines return HTML. They do not contain echos or prints themselves. The way the Geeklog system is designed; you usually put your code between Geeklog display routines. For example: code to display a page would look like this:  
  
The Geeklog plugin or block developer should have a good understanding of lib-common.php which contains most of the display routines as well as some other general purpose routines. All of the Geeklog display routines return html. They do not contain echos or prints themselves. The way the Geeklog system is designed; you usually put your code between Geeklog display routines. For example: code to display a page would look like this:
+
<pre>
 +
$display  = COM_siteHeader();
 +
$display .= COM_startBlock("Title of Your Block");
 +
$display .= "Some words";
 +
$display .= somefunction();
 +
$display .= COM_endBlock;
 +
$display .= COM_siteFooter(true);
 +
COM_output($display);
 +
</pre>
  
$display  = COM_siteHeader();<br>
+
A summary of commonly used Geeklog functions are described below but reference the [http://project.geeklog.net/src/Geeklog/_public_html---lib-common.php.html <tt>lib-common.php</tt> documentation] for further examples.
$display .= COM_startBlock("Title of Your Block");<br>
 
$display .= "Some words";<br>
 
$display .= somefunction();<br>
 
$display .= COM_endBlock;<br>
 
$display .= COM_siteFooter(true);<br>
 
echo $display;
 
  
A summary of commonly used Geeklog functions are described below but reference the attached lib-common.php documentation for further examples.
+
== lib-security.php ==
  
 +
The <tt>lib-security.php</tt> file contains the interface routines to the security system used in Geeklog. See the [http://project.geeklog.net/src/Geeklog/_system---lib-security.php.html <tt>lib-security.php</tt> documentation]. There are several SEC type functions that you may want to use in your projects. The table [[Geeklog's way of doing things#Commonly used Geeklog functions|Commonly Used Geeklog Functions]] at the end of this section defines a couple of the more commonly used functions.
  
 
lib-security.php:
 
The lib-security.php file contains the interface routines to the security system used in Geeklog. See the attached lib-security.php documentation. There are several SEC type functions that you may want to use in your projects. The table Commonly Used Geeklog Functions at the end of this section defines a couple of the more commonly used functions.
 
  
 +
== lib-database.php ==
  
+
All database access should take place through the database abstraction in <tt>lib-database.php</tt> and table names should be accessed through the <code>$_TABLES</code> array. The table definitions in this array will then include whatever table prefix this site is using.  You should ensure that your plugin or block uses the <code>$_TABLES['mytable']</code> for all database access related functions.
lib-database.php:
 
All database access should take place through the database abstraction in lib-database.php and table names should be accessed through the $_TABLES array. The table definitions in this array will then include whatever table prefix this site is using.  You should ensure that your plugin or block uses the $_TABLES['mytable'] for all Database access related functions.
 
Block developers and site admins installing the block need to edit the lib-database.php program and add the new $_TABLES entries for your block tables. Ensure you follow the same standard by using the $_DB_table_prefix.
 
Plugin developers need to define their tables in the plugin config.php file. You have the ability to use the $_TABLES array or use your own plugin specific array to maintain the table definitions. It's recommend that your arrays use a name such as _XX_TABLES, where XX are two letters to describe your plugin. Once the plugin is installed and enabled, the tables defined in the config.php for the plugin are automatically known as globals.  
 
  
 +
* Block developers and site admins installing the block need to make sure that any tables needed by a block are added to the <code>$_TABLES</code> array. Ensure you follow the same standard by using the $_DB_table_prefix. However, you should '''not''' edit <tt>lib-database.php</tt>. If no suitable place can be found in the block's code, the addition should be done in <tt>lib-custom.php</tt> instead.
 +
* Plugin developers need to define their tables in the plugin <tt>config.php</tt> file (or some other suitable file belonging to the plugin, e.g. <tt>functions.inc</tt>). You have the ability to use the <code>$_TABLES</code> array or use your own plugin specific array to maintain the table definitions. In the latter case it's recommend that your arrays use a name such as <code>_XX_TABLES</code>, where XX are two letters to describe your plugin. Once the plugin is installed and enabled, the tables defined for the plugin are automatically known as globals.
  
  
+
== lib-plugins.php ==
lib-plugins.php:
 
This library contains all the code used to interface your plugin or block to Geeklog. You will not call any code from here directly. The functions in this file are called by the Geeklog main programs as they are used to call all plugins and are used to resolve the plugin name and check if your plugin has a particular function. You will usually only have to look at this file to understand some nuance of the implementation. See the documentation for functions.inc and the original plugin documentation for further help.
 
  
 +
This library contains all the code used to interface your plugin or block to Geeklog. You will not call any code from here directly. The functions in this file are called by the Geeklog main programs as they are used to call all plugins and are used to resolve the plugin name and check if your plugin has a particular function. You will usually only have to look at this file to understand some nuance of the implementation. See the [[Functions.inc - Listing of the Plugin Functions|documentation for <tt>functions.inc</tt>]] and the original [[Plugin Development|plugin documentation]] for further help.
  
 
How your Plug-in or Block Interacts with Geeklog:
 
The program lib-common.php is the key to all interaction with Geeklog. It includes Geeklog's config.php and the rest of the Geeklog code libraries.
 
At the top of lib-common.php is an include of lib-custom.php. This is where you place all your block functions. They are then included when the site index.php is called.
 
  
At the very end of lib-common.php is a check for all enabled plugins. A plugin is registered with Geeklog when it has a record in the plugins table and the field pi_enabled is true. For all registered and enabled plugins, the code in lib-common.php will include the functions.inc file for each plugin. This is why the naming convention and location for each plugin file is strictly defined. All code libraries or configuration files your plugin needs should be included in your functions.inc. Since the plugins config.php is now also included this way - via the include in functions.inc - the variables in your plugin config.php become global and can be referenced in your plugin functions.
+
== How your Plugin or Block Interacts with Geeklog ==
 
Common Global Variables
 
There are a few commonly used globals within Geeklog that you will want to use and reference. The following table outlines the more frequently used ones and its recommended that these be used instead of hard coding paths and table names  in your links or project code.
 
  
Variable  Description
+
The program <tt>lib-common.php</tt> is the key to all interaction with Geeklog. It includes all of the Geeklog code libraries.
$_CONF['path_html'] Fully qualified path to your sites public_htmk path  
+
 
$_CONF['site_url'] Full URL to your sites public_html directory  
+
* At the top of <tt>lib-common.php</tt> is an include of <tt>lib-custom.php</tt>. This is where you place all your block functions. They are then included when the site <tt>index.php</tt> is called.
$_CONF['site_admin_url'] Full URL to your sites admin directory  
+
* At the very end of <tt>lib-common.php</tt> is a check for all enabled plugins. A plugin is registered with Geeklog when it has a record in the plugins table and the field <tt>pi_enabled</tt> is <tt>1</tt>. For all registered and enabled plugins, the code in <tt>lib-common.php</tt> will include the <tt>functions.inc</tt> file for each plugin. This is why the naming convention and location for each plugin file is strictly defined. All code libraries or configuration files your plugin needs should be included in your <tt>functions.inc</tt>. Since the plugin's <tt>config.php</tt> (if it exists) is now also included this way - via the include in <tt>functions.inc</tt> - the variables in your plugin <tt>config.php</tt> become global and can be referenced in your plugin functions.
$_USER['uid'] Current user ID. A uid of 1 is an anonymous user  
+
 
$_TABLES['tablename'] A array of geeklog tables with the site prefix defined.  
+
 
 +
== Common Global Variables ==
 +
 
 +
There are a few commonly used globals within Geeklog that you will want to use and reference. The following table outlines the more frequently used ones and its recommended that these be used instead of hard coding paths and table names in your links or project code.
 +
 
 +
<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="75%" id="AutoNumber2" height="72">
 +
  <tr>
 +
    <td width="27%" bgcolor="#000000" height="16">
 +
    <font color="#FFFFFF" size="2">&nbsp;Variable</font></td>
 +
    <td width="73%" bgcolor="#000000" height="16">
 +
    <font color="#FFFFFF" size="2">&nbsp; Description</font></td>
 +
   </tr>
 +
  <tr>
 +
    <td width="27%" height="17"><font size="2">$_CONF['path_html']</font></td>
 +
    <td width="73%" height="17"><font size="2">Fully qualified path to your site's public_html path</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="27%" height="18"><font size="2">$_CONF['site_url']</font></td>
 +
    <td width="73%" height="18"><font size="2">Full URL to your site's public_html directory</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="27%" height="18"><font size="2">$_CONF['site_admin_url']</font></td>
 +
    <td width="73%" height="18"><font size="2">Full URL to your site's admin directory</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="27%" height="18"><font size="2">$_USER['uid']</font></td>
 +
    <td width="73%" height="18"><font size="2">Current user ID. A uid of 1 is an anonymous user.<br/>Note: This variable may not be set, which also should be handled as an anonymous user. Use the function <code>COM_isAnonUser()</code> to find out whether the user is anonymous.</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="27%" height="18"><font size="2">$_TABLES['tablename']</font></td>
 +
    <td width="73%" height="18"><font size="2">An array of Geeklog tables with the site prefix defined. This can be used to access specific tables for queries.</font></td>
 +
  </tr>
 +
</table>
 +
 
 +
== Commonly used Geeklog functions ==
  
 
Commonly used Geeklog functions
 
 
The following is a list of commonly used Geeklog functions that as developers we use and recommend you become more familiar with and use in your development projects. You will find example usage of these functions throughout the Geeklog code.  
 
The following is a list of commonly used Geeklog functions that as developers we use and recommend you become more familiar with and use in your development projects. You will find example usage of these functions throughout the Geeklog code.  
  
Function Name
+
<table border="1" style="border-collapse: collapse" bordercolor="#111111" width="100%" id="AutoNumber1" height="197" cellpadding="3" cellspacing="0">
     Description  
+
  <tr>
COM_siteHeader
+
    <td width="13%" bgcolor="#000000" height="18">
Display the main site header and optionally if 'none' is passed do not display the left blocks  
+
    <font color="#FFFFFF" size="2">&nbsp;Function Name</font></td>
COM_siteFooter
+
    <td width="73%" bgcolor="#000000" height="18">
Display the main site footer and optionally if 'true' is passed display the right blocks  
+
     <font color="#FFFFFF" size="2">&nbsp;&nbsp; Description</font></td>
COM_startBlock
+
  </tr>
Formats the block title using the selected theme - pass the title, helpfile if any and optional block theme to apply if you do not want to use default  
+
  <tr>
COM_endBlock
+
    <td width="13%" height="16">
Formats the block footer using the selected theme or the optional block theme if you do not want to use default  
+
    <font size="2">&nbsp;COM_siteHeader</font></td>
COM_errorLOG Use to format an error message or use for debugging - view output in <geeklog_dir>/logs/error.log  
+
    <td width="73%" height="16"><font size="2">Display the main site header and optionally if 'none' is passed <b>do not </b>display the left blocks</font></td>
DB_query
+
  </tr>
Execute a formatted SQL query and return the record set to an array of records (which is also an array)  
+
  <tr>
DB_fetchArray
+
    <td width="13%" height="16">
Retrieve a record as an array from the returned record set - which DB_query returned.  
+
    <font size="2">&nbsp;COM_siteFooter</font></td>
DB_numROWS
+
    <td width="73%" height="16"><font size="2">Display the main site footer and optionally if 'true' is passed display the right blocks</font></td>
Returns the number of records retrieved by the DB_query result  
+
  </tr>
DB_getItem Retrieve one record as an array. Pass a formatted SQL stmt with WHERE clause to retrieve one record
+
  <tr>
COM_checkHTML Use to strip out $, <, > , [code] and replace with the HTML codes  
+
    <td width="13%" height="32">
COM_checkWords Use to check passed text for any HTML tags that are not allowed as per the site config.php setting  
+
    <font size="2">&nbsp;COM_startBlock</font></td>
SEC_inGroup Used to check if user has passed group rights. Example: SEC_inGroup('Root') - returns true if user is  
+
    <td width="73%" height="32"><font size="2">Formats the block title using the selected theme - pass the title, helpfile if any and optional block theme to apply if you do not want to use default</font></td>
SEC_hasRights Used to check if user has access right (feature). Example: SEC_hasRights('myplugin.edit')
+
  </tr>
 +
  <tr>
 +
    <td width="13%" height="16">
 +
    <font size="2">&nbsp;COM_endBlock</font></td>
 +
    <td width="73%" height="16"><font size="2">Formats the block footer using the selected theme or the optional block theme if you do not want to use default</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="16">
 +
    <font size="2">&nbsp;COM_output</font></td>
 +
    <td width="73%" height="16"><font size="2">Takes the <code>$display</code> HTML string and echoes it out to the page. This function has been defined to allow compatibility with compressed content. </font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="12"><font size="2">&nbsp;COM_errorLog</font></td>
 +
    <td width="73%" height="12"><font size="2">Use to format an error message or use for debugging - view output in &lt;geeklog_dir&gt;/logs/error.log</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="14">
 +
    <font size="2">&nbsp;DB_query</font></td>
 +
    <td width="73%" height="14"><font size="2">Execute a formatted SQL query and return the record set to an array of records (which is also an array)</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="16">
 +
    <font size="2">&nbsp;DB_fetchArray</font></td>
 +
    <td width="73%" height="16"><font size="2">Retrieve a record as an array from the returned record set - which DB_query returned.</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="16">
 +
    <font size="2">&nbsp;DB_numRows</font></td>
 +
    <td width="73%" height="16"><font size="2">Returns the number of records retrieved by the DB_query result</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="16"><font size="2">&nbsp;DB_getItem</font></td>
 +
    <td width="73%" height="16"><font size="2">Retrieve one record as an array.</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;COM_checkHTML</font></td>
 +
    <td width="73%" height="15"><font size="2">Use to strip out $, &lt;, &gt; , [code] and replace with the HTML codes</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;COM_checkWords</font></td>
 +
    <td width="73%" height="15"><font size="2">Use to check passed text for any HTML tags that are not allowed as per the site config.php setting</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;COM_getArgument</font></td>
 +
    <td width="73%" height="15"><font size="2">Use to get a specified variable from the query string</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;COM_setArgNames</font></td>
 +
    <td width="73%" height="15"><font size="2">Set the names of the global variables that your code expects to see in the query string.</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;SEC_inGroup</font></td>
 +
    <td width="73%" height="15"><font size="2">Used to check if user has passed group rights.<br/>Example: SEC_inGroup('Root') - returns true if user is a member of the "Root" group</font></td>
 +
  </tr>
 +
  <tr>
 +
    <td width="13%" height="15"><font size="2">&nbsp;SEC_hasRights</font></td>
 +
    <td width="73%" height="15"><font size="2">Used to check if user has access right (feature).<br/>Example: SEC_hasRights('myplugin.edit')</font></td>
 +
  </tr>
 +
</table>
 +
 
 +
 
 +
[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Latest revision as of 18:37, 16 April 2010

All of Geeklog's PHP files are pure PHP. PHP allows you to use PHP as a scripting language embedded in HTML files but this is not how Geeklog does it. All of Geeklog's PHP files must have <?php as the first five characters and end with ?>. Failure to structure your Geeklog files this way will cause session and header errors. Geeklog attempts as much as possible to have only PHP code in the .php files. Two of the conventions used in Geeklog to accomplish this are the use of templates and language files.

Time will be well spent by the Geeklog plugin or block developer to become familiar with several Geeklog libraries. The following section outlines the more important or frequently used libraries, functions and standards.


lib-common.php

The Geeklog plugin or block developer should have a good understanding of lib-common.php which contains most of the display routines as well as some other general purpose routines. All of the Geeklog display routines return HTML. They do not contain echos or prints themselves. The way the Geeklog system is designed; you usually put your code between Geeklog display routines. For example: code to display a page would look like this:

$display  = COM_siteHeader();
$display .= COM_startBlock("Title of Your Block");
$display .= "Some words";
$display .= somefunction();
$display .= COM_endBlock;
$display .= COM_siteFooter(true);
COM_output($display);

A summary of commonly used Geeklog functions are described below but reference the lib-common.php documentation for further examples.

lib-security.php

The lib-security.php file contains the interface routines to the security system used in Geeklog. See the lib-security.php documentation. There are several SEC type functions that you may want to use in your projects. The table Commonly Used Geeklog Functions at the end of this section defines a couple of the more commonly used functions.


lib-database.php

All database access should take place through the database abstraction in lib-database.php and table names should be accessed through the $_TABLES array. The table definitions in this array will then include whatever table prefix this site is using. You should ensure that your plugin or block uses the $_TABLES['mytable'] for all database access related functions.

  • Block developers and site admins installing the block need to make sure that any tables needed by a block are added to the $_TABLES array. Ensure you follow the same standard by using the $_DB_table_prefix. However, you should not edit lib-database.php. If no suitable place can be found in the block's code, the addition should be done in lib-custom.php instead.
  • Plugin developers need to define their tables in the plugin config.php file (or some other suitable file belonging to the plugin, e.g. functions.inc). You have the ability to use the $_TABLES array or use your own plugin specific array to maintain the table definitions. In the latter case it's recommend that your arrays use a name such as _XX_TABLES, where XX are two letters to describe your plugin. Once the plugin is installed and enabled, the tables defined for the plugin are automatically known as globals.


lib-plugins.php

This library contains all the code used to interface your plugin or block to Geeklog. You will not call any code from here directly. The functions in this file are called by the Geeklog main programs as they are used to call all plugins and are used to resolve the plugin name and check if your plugin has a particular function. You will usually only have to look at this file to understand some nuance of the implementation. See the documentation for functions.inc and the original plugin documentation for further help.


How your Plugin or Block Interacts with Geeklog

The program lib-common.php is the key to all interaction with Geeklog. It includes all of the Geeklog code libraries.

  • At the top of lib-common.php is an include of lib-custom.php. This is where you place all your block functions. They are then included when the site index.php is called.
  • At the very end of lib-common.php is a check for all enabled plugins. A plugin is registered with Geeklog when it has a record in the plugins table and the field pi_enabled is 1. For all registered and enabled plugins, the code in lib-common.php will include the functions.inc file for each plugin. This is why the naming convention and location for each plugin file is strictly defined. All code libraries or configuration files your plugin needs should be included in your functions.inc. Since the plugin's config.php (if it exists) is now also included this way - via the include in functions.inc - the variables in your plugin config.php become global and can be referenced in your plugin functions.


Common Global Variables

There are a few commonly used globals within Geeklog that you will want to use and reference. The following table outlines the more frequently used ones and its recommended that these be used instead of hard coding paths and table names in your links or project code.

 Variable   Description
$_CONF['path_html'] Fully qualified path to your site's public_html path
$_CONF['site_url'] Full URL to your site's public_html directory
$_CONF['site_admin_url'] Full URL to your site's admin directory
$_USER['uid'] Current user ID. A uid of 1 is an anonymous user.
Note: This variable may not be set, which also should be handled as an anonymous user. Use the function COM_isAnonUser() to find out whether the user is anonymous.
$_TABLES['tablename'] An array of Geeklog tables with the site prefix defined. This can be used to access specific tables for queries.

Commonly used Geeklog functions

The following is a list of commonly used Geeklog functions that as developers we use and recommend you become more familiar with and use in your development projects. You will find example usage of these functions throughout the Geeklog code.

 Function Name    Description
 COM_siteHeader Display the main site header and optionally if 'none' is passed do not display the left blocks
 COM_siteFooter Display the main site footer and optionally if 'true' is passed display the right blocks
 COM_startBlock Formats the block title using the selected theme - pass the title, helpfile if any and optional block theme to apply if you do not want to use default
 COM_endBlock Formats the block footer using the selected theme or the optional block theme if you do not want to use default
 COM_output Takes the $display HTML string and echoes it out to the page. This function has been defined to allow compatibility with compressed content.
 COM_errorLog Use to format an error message or use for debugging - view output in <geeklog_dir>/logs/error.log
 DB_query Execute a formatted SQL query and return the record set to an array of records (which is also an array)
 DB_fetchArray Retrieve a record as an array from the returned record set - which DB_query returned.
 DB_numRows Returns the number of records retrieved by the DB_query result
 DB_getItem Retrieve one record as an array.
 COM_checkHTML Use to strip out $, <, > , [code] and replace with the HTML codes
 COM_checkWords Use to check passed text for any HTML tags that are not allowed as per the site config.php setting
 COM_getArgument Use to get a specified variable from the query string
 COM_setArgNames Set the names of the global variables that your code expects to see in the query string.
 SEC_inGroup Used to check if user has passed group rights.
Example: SEC_inGroup('Root') - returns true if user is a member of the "Root" group
 SEC_hasRights Used to check if user has access right (feature).
Example: SEC_hasRights('myplugin.edit')