GeeklogWiki - User contributions [en]

Themes and XHTML

2012-04-15T13:40:05Z

Roccivic:

Since version 1.5.0, Geeklog supports [http://en.wikipedia.org/wiki/XHTML XHTML] compliant themes. This means that Geeklog will automatically create XHTML compliant tags when required.

== Switching to XHTML ==

Since Geeklog 2.0, you must specify a doctype for your theme, if you wish for your theme to be XHTML compliant.
This is done in the functions.php file by implementing the function theme_config_yourThemeName() method, for example, for a theme called foobar this would look like:

function theme_config_foobar()
{
return array(
'doctype' => 'xhtml10strict'
);
}

Valid XHTML doctypes are:

* xhtml10transitional
* xhtml10strict

== Switching to XHTML in Geeklog < 2.0 ==

Whether Geeklog will switch to XHTML compliant mode or not depends on the definition of an <tt>XHTML</tt> variable in the PHP code. This variable can either be defined by the theme (in the theme's <tt>functions.php</tt> file) or by selecting an XHTML DOCTYPE from the Configuation (since Geeklog 1.6.0):

: Configuration > Geeklog > Theme > Theme > [http://www.geeklog.net/docs/english/config.html#desc_doctype DOCTYPE Declaration]

Selecting an XHTML DOCTYPE will automatically set the <tt>XHTML</tt> constant properly (any definition made by the theme still takes precedence, though, so make sure the two don't conflict).

== XHTML Constant ==

For an XHTML compliant theme, the <tt>XHTML</tt> constant should be defined like so:

<pre>define('XHTML', ' /');</pre>

Otherwise, the constant will be defined as an empty string:

<pre>define('XHTML', '');</pre>

Plugins can simply use the <tt>XHTML</tt> constant - Geeklog will take care that is always defined. The same is true for code in <tt>lib-custom.php</tt>, with the exception of code that is not located in a function (since <tt>lib-custom.php</tt> will be included before the theme, and any global code in <tt>lib-custom.php</tt> would therefore be executed before the constant is defined).

== Template Variables ==

The definition of the <tt>XHTML</tt> constant is also available as a <tt>{xhtml}</tt> template variable in all template files used by Geeklog. This way, it is possible to create themes that will work both as XHTML and "plain" HTML by using the template variable for tags that have to be closed in XHTML, e.g.

<pre><br{xhtml}>
<input type="submit" name="test"{xhtml}>
<img src="image.png" alt=""{xhtml}></pre>

=== Other Template Variables ===

Themes that are written to be both valid HTML and XHTML (as described above) should use the <tt>{doctype}</tt> variable as the first line in <tt>header.thtml</tt> instead of hard-coding the DOCTYPE.

In XHTML mode, Geeklog will also provide a <tt>{xmlns}</tt> variable that will contain the <tt>xmlns</tt> attribute for the <tt>html</tt> element.

Putting it all together, the first 3 lines of your theme's <tt>header.thtml</tt> should look like this:

<pre>{doctype}
<html{lang_attribute}{xmlns}>
<head></pre>

The <tt>{lang_attribute}</tt> will set a <tt>lang</tt> attribute in [[Multilingual Support|multi-language setups]].

The Professional theme that ships with Geeklog uses the <tt>{doctype}</tt> template variable and is both HTML and XHTML compliant, depending on the DOCTYPE selected in the Configuration.

[[Category:Themes]]

Theme Developers Guide

2012-04-15T13:34:38Z

Roccivic:

Creating a theme for Geeklog is easy and quite fast. If you can manipulate HTML files then you can create a theme! There's no need to learn PHP.

== Creating a theme ==

First, copy an existing theme that is most similar to what you want to implement (if one exists). If what you will do is radically different (and we hope so!) then copying any one will do. Copy the existing theme to the name you want your theme to have (please, no spaces in the theme name):

cp -R /path/to/geeklog/public_html/layout/Yahoo /path/to/geeklog/public_html/layout/My_Theme_Name_No_Spaces

Change into your new theme directory:

cd /path/to/geeklog/public_html/layout/My_Theme_Name_No_Spaces

Now edit the templates to suit your needs. Keep in mind that templates, generally are partial HTML files. The directory you just created holds ALL templates Geeklog needs but you will only need to modify a small few to make a huge impact on the look.

In particular these are the templates you will undoubtedly want to change:

*header.thtml
*footer.thtml
*blockheader.thtml
*blockfooter.thtml
*storybody.thtml
*storybodytext.thtml
*featuredstorybody.thtml
*featuredstorybodytext.thtml
*style.css

== How themes work ==

When rendering a theme, Geeklog starts with header.thtml which builds the site's header and then goes on to include the left column of blocks (look for the variable {left_blocks} and the leftblocks.thtml file). The middle part of a site consists of the stories which are built using the storytext.thtml and storybodytext.thtml (for normal stories) and featuredstorytext.thtml and featuredstorybodytext.thtml (for featured stories) template files. The footer.thtml file then builds the right column of blocks (variable {right_blocks}, file right_blocks.thtml) and the site's footer. Blocks themselves consist of the blockheader.thtml and blockfooter.thtml files.

The above only described how Geeklog's main page and stories are rendered. More templates exist for the various editors and lists you will see in Geeklog, as well as for the calendar and almost every other part of Geeklog.

There is currently no complete list available that explains which template file is used for which part of Geeklog. However, in most cases the use should be obvious when you have a look at the file and directory names in your theme's layout directory. If you're unsure which template file is used to render a certain part of Geeklog, have a look at the URL. You will notice the name of a PHP file there, e.g. the users.php file when you view a user's profile. Open that file and search for '.thtml'. For the profile you will find these lines (in function userprofile()):

;$user_templates = COM_newTemplate ($_CONF['path_layout'] . 'users');
;$user_templates->set_file (array ('profile'=>'profile.thtml', 'row'=>'commentrow.thtml', 'strow'=>'storyrow.thtml'));

You don't need to understand PHP code to see that this uses the template files profile.thtml, commentrow.thtml, and storyrow.thtml. The first line also indicates that these are taken from the users directory within the theme's layout directory.

An [http://www.geeklog.net/docs/english/themevars.html incomplete list of variables] that can be used in templates files is also included.

== Testing a theme and further information ==

After you have edited your themes, you are now ready to test it out. Simply go to <nowiki>http://mygeeklogsite/users.php?mode=preferences</nowiki> - in the theme drop-down select your newly created theme (note the name of your theme is the same name as the directory for your theme).

Finally, you may want to update the logo and other images in your theme's images directory.

For the template system we are using [http://phplib.sourceforge.net/ PHPLib]'s template class. Read their documentation and, optionally, look at /path/to/geeklog/system/classes/template.class.php to see how it is implemented. Even with this knowledge it may not be clear which templates are used in conjunction with one another (i.e. storybody.thtml and storybodytext.thtml together make up the complete format of a single story). If you have questions join our mailing list at http://lists.geeklog.net/listinfo/geeklog-users or check us out in IRC at irc.freenode.net in #geeklog.

== Theme API ==

Since Geeklog 2.0, a minimal theme API is available. It can be used to override defaults, load CSS files and load JavaScript files.
The API is structured similarly to that of the Geeklog plugins. In the file "functions.php" in the theme's folder, the following functions may be declared (replace yourThemeName with the actual theme name):

* function theme_config_yourThemeName() {}
* function theme_css_yourThemeName() {}
* function theme_js_libs_yourThemeName() {}
* function theme_js_files_yourThemeName() {}
* function theme_init_yourThemeName() {}

For implementation details please see the functions.php file that was shipped with your version of Geeklog.

== Tips and tricks ==

'''Themes and WYSIWG editors''': The template files used by Geeklog are not complete HTML files - they contain only parts of the HTML that Geeklog puts together to build a proper HTML document. This, however, seems to confuse some WYSIWYG HTML editors and some of them tend to add the HTML which they think is missing from the file, thus making it unusable for Geeklog.
We suggest you use a simple text editor to edit your themes.

'''PHP in themes''': You can use PHP in the header of a theme, i.e. in the header.thtml file. If you want to use custom PHP functions, you can put them in the file functions.php within your themes directory.

'''Different look for left and right blocks''': You can give the blocks on the left and right a different look. See [http://www.geeklog.net/forum/viewtopic.php?forum=10&showtopic=21070 this story on the Geeklog homepage] for details.

'''Polls''': To use multi-colored bars in the graphical display of poll results, you can use the {answer_counter} and {answer_odd} variables in the pollbooth/pollvotes_bar.thtml template file. {answer_counter} will be replaced with a running number for each answer, hence bar{answer_counter}.gif would result in bar1.gif, bar2.gif, etc. Giving each of those GIFs a different color would give you a different color for each answer.
{answer_odd} will alternate between 0 and 1 for every answer, hence bar{answer_odd}.gif will result in bar0.gif for the first, third, fifth, etc. answer and bar1.gif for the second, fourth, etc. answer.

'''XHTML''': [[Themes and XHTML]]

[[Category:Themes]]

Plugin Autoinstall

2011-05-02T14:58:43Z

Roccivic:

= Introduction =

Geeklog 1.6 brings two important changes regarding installation of plugins:

* Plugins can be installed by uploading their tarball (from Geeklog's Plugins Admin panel)
* Plugins can be bundled / unbundled by simply adding / removing their respective directories to / from the Geeklog tarball

In both of these scenarios, Geeklog needs a way to automatically run the install procedure for such a plugin.

The problem with the plugin install scripts used until now are that they were mainly aimed at being run by a human and that they also check permissions that simply may not be set when the install is done (e.g. when running Geeklog's install script).

The solution proposed here is the inclusion of a new file, <tt>autoinstall.php</tt> into every plugin that implements up to 4 new API functions (3 of which are optional).

= autoinstall.php =

The file <tt>autoinstall.php</tt> is to be located in the plugin's main directory, i.e. in the same directory as its <tt>functions.inc</tt> file:

<pre>/path/to/geeklog/plugins/
foo/
functions.inc
autoinstall.php
staticpages/
functions.inc
autoinstall.php
...</pre>

Plugins that ship with an <tt>autoinstall.php</tt> file won't need to provide the "traditional" install script (<tt>admin/plugins/foo/install.php</tt>) unless they want to be backward-compatible with Geeklog releases prior to 1.6.

== plugin_autoinstall_ ==

This is the most important and mandatory API function to implement in <tt>autoinstall.php</tt>:

<pre>function plugin_autoinstall_foo($pi_name)
{
$pi_name = 'foo';
$pi_display_name = 'Foo';
$pi_admin = $pi_display_name . ' Admin';

$info = array(
'pi_name' => $pi_name,
'pi_display_name' => $pi_display_name,
'pi_version' => '1.0.0',
'pi_gl_version' => '1.6.0',
'pi_homepage' => 'http://www.example.com/'
);

$groups = array(
$pi_admin => 'Has full access to ' . $pi_display_name . ' features'
);

$features = array(
$pi_name . '.edit' => 'Access to ' . $pi_display_name . ' editor'
);

$mappings = array(
$pi_name . '.edit' => array($pi_admin)
);

$tables = array(
'foo'
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables
);

return $inst_parms;
}</pre>

If you've written a Geeklog plugin before, the data provided by this function should look familiar.

The <code>$info</code> array provides the information that goes into the plugin's entry in the <tt>gl_plugins</tt> table. The only addition here is the <code>$pi_display_name</code> entry, so that we can use a nicely formatted name to present to the user instead of having to refer to the plugin by its internal and possibly abbreviated name (<code>$pi_name</code>).

<code>$groups</code> and <code>$features</code> simply list all the groups and features (permissions) that the plugin would like to introduce. Geeklog will create those automatically for the plugin, using the <code>$mappings</code>. <code>$mappings</code> defines which permissions to assign to which of the new groups.

The <code>$tables</code> array obviously lists all the table names used by the plugin (note that the names are given without the <code>$_DB_table_prefix</code>). Geeklog will add these tables names (with the proper prefix) to the global <code>$_TABLES</code> array during the install. The plugin will still have to make sure they are known after the install, e.g. by defining them in its <tt>functions.inc</tt> file.

Finally, all these arrays are wrapped into another array and returned from the autoinstall function.

With the exception of the <code>$info</code> array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide <code>$groups</code> or <code>$tables</code> entries.

In case of an error during the install, Geeklog will also use this information to attempt a cleanup of the database, i.e. remove groups, permissions, etc.

=== Plugin dependencies and version control ===

Since Geeklog 1.8.0, a new and optional array, $requires, is available. It must contain dependency information for a plugin.
You can make a requirement for a particular range of versions of Geeklog, databases and other plugins.
Each dependency is stored inside this array as another array.

The minimal usage is as follows:
<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and does not need a databases to function.
array('plugin' => 'someplugin')
);
...
</pre>

<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and supports MySQL and PgSQL databases.
array('plugin' => 'someplugin'),
array('db' => 'mysql'),
array('db' => 'pgsql')
);
...
</pre>

You can define any particular range of versions as the requirements for your plugin by adding the 'version' and 'operator' indeces to the arrays. Here's a more complex example:
<pre>
...

$requires= array(
// This plugin requires a version greater than or equal to 1.0.0 of 'someplugin' (The default 'operator' is '>=')
array('plugin' => 'someplugin',
'version' => '1.0.0'),

// This plugin also requires a version greater than 1.0.0 of 'someotherplugin'
array('plugin' => 'someotherplugin',
'version' => '1.0.0',
'operator' => '>'),

// Multiple dependencies are allowed for the same parent plugin
// The below line ensures that only 'someplugin' with version less than 2.0.0 is used
array('plugin' => 'someotherplugin',
'version' => '2.0.0',
'operator' => '<'),

// You can also require a particular range of versions of geeklog
array('core' => 'geeklog',
'version' => '1.8.0'),

// You must require either all or none of the databases that your plugin supports
// Or you might lock out some of the capabilities of your plugin
array('db' => 'mysql'),

array('db' => 'mssql',
'version' => '9.0'), // At least SQL Server 2005

array('db' => 'pgsql',
'version' => '7.3',
'operator' => '>')
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables,
'requires' => $requires // Add the dependency information to the installation parameters here
);

...</pre>

'''Note:''' Expect this function to be called more than once during installation. Also, the fact that the function is being called at all does not necessarily mean that the plugin will actually be installed.

== plugin_postinstall_ ==

Geeklog, armed with the information provided by the <code>plugin_autoinstall_</code> function, will take care of moving the plugin's files into their 3 standard locations, create the tables, the groups, and permissions. For any additional steps that need to be performed during installation, the <code>plugin_postinstall_</code> function will be called:

<pre>function plugin_postinstall_foo($pi_name)</pre>

At this point, all the files are already in their correct place, the groups and permissions have been added and the plugin has been registered with Geeklog (i.e. has been added to the <tt>gl_plugins</tt> table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.

== plugin_compatible_with_this_version_ ==

The very first function from <tt>autoinstall.php</tt> that Geeklog attempts to call is <code>plugin_compatible_with_this_version_</code>. Here, the plugin can check if it's compatible with the current Geeklog version. Since this function was only introduced in Geeklog 1.6.0, you can assume this to be the minimum version.

<pre>function plugin_compatible_with_this_version_foo($pi_name)</pre>

The function should return <code>false</code> when the plugin requires a more recent Geeklog version. Return <code>true</code> if installation on the current Geeklog version is okay.

If you would like to rely on Geeklog's "Plugin dependencies and version control" feature for ensuring that all required plugin are available, you must ensure that the user has at least version 1.8.0 of Geeklog. This can be accomplished with the following code snippet:

<pre>function plugin_compatible_with_this_version_foo($pi_name) {
if (function_exists('PLG_resolveDependencies')) {
return true;
} else {
COM_errorLog('Plugin "foo" requires at least Geeklog 1.8.0, but you are running an older version.');
return false;
}
}</pre>

== plugin_load_configuration_ ==

This function only needs to be implemented by plugins that use the [[PluginConfiguration|Configuration GUI]]. A typical implementation would look like this:

<pre>function plugin_load_configuration_foo($pi_name)
{
global $_CONF;

$base_path = $_CONF['path'] . 'plugins/' . $pi_name . '/';

require_once $_CONF['path_system'] . 'classes/config.class.php';
require_once $base_path . 'install_defaults.php';

return plugin_initconfig_foo();
}</pre>

Where the <code>plugin_initconfig_foo</code> function is implemented in a <tt>install_defaults.php</tt> file, that handles creation and updates of the plugin's config GUI elements.

= Also see =

* [[Plugin Auto-Uninstall]]

[[Category:Plugin Development]]

Plugin Autoinstall

2011-03-13T21:10:44Z

Roccivic:

= Introduction =

Geeklog 1.6 brings two important changes regarding installation of plugins:

* Plugins can be installed by uploading their tarball (from Geeklog's Plugins Admin panel)
* Plugins can be bundled / unbundled by simply adding / removing their respective directories to / from the Geeklog tarball

In both of these scenarios, Geeklog needs a way to automatically run the install procedure for such a plugin.

The problem with the plugin install scripts used until now are that they were mainly aimed at being run by a human and that they also check permissions that simply may not be set when the install is done (e.g. when running Geeklog's install script).

The solution proposed here is the inclusion of a new file, <tt>autoinstall.php</tt> into every plugin that implements up to 4 new API functions (3 of which are optional).

= autoinstall.php =

The file <tt>autoinstall.php</tt> is to be located in the plugin's main directory, i.e. in the same directory as its <tt>functions.inc</tt> file:

<pre>/path/to/geeklog/plugins/
foo/
functions.inc
autoinstall.php
staticpages/
functions.inc
autoinstall.php
...</pre>

Plugins that ship with an <tt>autoinstall.php</tt> file won't need to provide the "traditional" install script (<tt>admin/plugins/foo/install.php</tt>) unless they want to be backward-compatible with Geeklog releases prior to 1.6.

== plugin_autoinstall_ ==

This is the most important and mandatory API function to implement in <tt>autoinstall.php</tt>:

<pre>function plugin_autoinstall_foo($pi_name)
{
$pi_name = 'foo';
$pi_display_name = 'Foo';
$pi_admin = $pi_display_name . ' Admin';

$info = array(
'pi_name' => $pi_name,
'pi_display_name' => $pi_display_name,
'pi_version' => '1.0.0',
'pi_gl_version' => '1.6.0',
'pi_homepage' => 'http://www.example.com/'
);

$groups = array(
$pi_admin => 'Has full access to ' . $pi_display_name . ' features'
);

$features = array(
$pi_name . '.edit' => 'Access to ' . $pi_display_name . ' editor'
);

$mappings = array(
$pi_name . '.edit' => array($pi_admin)
);

$tables = array(
'foo'
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables
);

return $inst_parms;
}</pre>

If you've written a Geeklog plugin before, the data provided by this function should look familiar.

The <code>$info</code> array provides the information that goes into the plugin's entry in the <tt>gl_plugins</tt> table. The only addition here is the <code>$pi_display_name</code> entry, so that we can use a nicely formatted name to present to the user instead of having to refer to the plugin by its internal and possibly abbreviated name (<code>$pi_name</code>).

<code>$groups</code> and <code>$features</code> simply list all the groups and features (permissions) that the plugin would like to introduce. Geeklog will create those automatically for the plugin, using the <code>$mappings</code>. <code>$mappings</code> defines which permissions to assign to which of the new groups.

The <code>$tables</code> array obviously lists all the table names used by the plugin (note that the names are given without the <code>$_DB_table_prefix</code>). Geeklog will add these tables names (with the proper prefix) to the global <code>$_TABLES</code> array during the install. The plugin will still have to make sure they are known after the install, e.g. by defining them in its <tt>functions.inc</tt> file.

Finally, all these arrays are wrapped into another array and returned from the autoinstall function.

With the exception of the <code>$info</code> array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide <code>$groups</code> or <code>$tables</code> entries.

In case of an error during the install, Geeklog will also use this information to attempt a cleanup of the database, i.e. remove groups, permissions, etc.

'''Plugin dependencies and version control'''

Since Geeklog 1.8.0, a new and optional array, $requires, is available. It must contain dependency information for a plugin.
You can make a requirement for a particular range of versions of Geeklog, databases and other plugins.
Each dependency is stored inside this array as another array.

The minimal usage is as follows:
<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and does not need a databases to function.
array('plugin' => 'someplugin')
);
...
</pre>

<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and supports MySQL and PgSQL databases.
array('plugin' => 'someplugin'),
array('db' => 'mysql'),
array('db' => 'pgsql')
);
...
</pre>

You can define any particular range of versions as the requirements for your plugin by adding the 'version' and 'operator' indeces to the arrays. Here's a more complex example:
<pre>
...

$requires= array(
// This plugin requires a version greater than or equal to 1.0.0 of 'someplugin' (The default 'operator' is '>=')
array('plugin' => 'someplugin',
'version' => '1.0.0'),

// This plugin also requires a version greater than 1.0.0 of 'someotherplugin'
array('plugin' => 'someotherplugin',
'version' => '1.0.0',
'operator' => '>'),

// Multiple dependencies are allowed for the same parent plugin
// The below line ensures that only 'someplugin' with version less than 2.0.0 is used
array('plugin' => 'someotherplugin',
'version' => '2.0.0',
'operator' => '<'),

// You can also require a particular range of versions of geeklog
array('core' => 'geeklog',
'version' => '1.8.0'),

// You must require either all or none of the databases that your plugin supports
// Or you might lock out some of the capabilities of your plugin
array('db' => 'mysql'),

array('db' => 'mssql',
'version' => '9.0'), // At least SQL Server 2005

array('db' => 'pgsql',
'version' => '7.3',
'operator' => '>')
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables,
'requires' => $requires // Add the dependency information to the installation parameters here
);

...</pre>

'''Note:''' Expect this function to be called more than once during installation. Also, the fact that the function is being called at all does not necessarily mean that the plugin will actually be installed.

== plugin_postinstall_ ==

Geeklog, armed with the information provided by the <code>plugin_autoinstall_</code> function, will take care of moving the plugin's files into their 3 standard locations, create the tables, the groups, and permissions. For any additional steps that need to be performed during installation, the <code>plugin_postinstall_</code> function will be called:

<pre>function plugin_postinstall_foo($pi_name)</pre>

At this point, all the files are already in their correct place, the groups and permissions have been added and the plugin has been registered with Geeklog (i.e. has been added to the <tt>gl_plugins</tt> table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.

== plugin_compatible_with_this_version_ ==

The very first function from <tt>autoinstall.php</tt> that Geeklog attempts to call is <code>plugin_compatible_with_this_version_</code>. Here, the plugin can check if it's compatible with the current Geeklog version. Since this function was only introduced in Geeklog 1.6.0, you can assume this to be the minimum version.

<pre>function plugin_compatible_with_this_version_foo($pi_name)</pre>

The function should return <code>false</code> when the plugin requires a more recent Geeklog version. Return <code>true</code> if installation on the current Geeklog version is okay.

If you would like to rely on Geeklog's "Plugin dependencies and version control" feature for ensuring that all required plugin are available, you must ensure that the user has at least version 1.8.0 of Geeklog. This can be accomplished with the following code snippet:

<pre>function plugin_compatible_with_this_version_foo($pi_name) {
if (function_exists('PLG_resolveDependencies')) {
return true;
} else {
COM_errorLog('Plugin "foo" requires at least Geeklog 1.8.0, but you are running an older version.');
return false;
}
}</pre>

== plugin_load_configuration_ ==

This function only needs to be implemented by plugins that use the [[PluginConfiguration|Configuration GUI]]. A typical implementation would look like this:

<pre>function plugin_load_configuration_foo($pi_name)
{
global $_CONF;

$base_path = $_CONF['path'] . 'plugins/' . $pi_name . '/';

require_once $_CONF['path_system'] . 'classes/config.class.php';
require_once $base_path . 'install_defaults.php';

return plugin_initconfig_foo();
}</pre>

Where the <code>plugin_initconfig_foo</code> function is implemented in a <tt>install_defaults.php</tt> file, that handles creation and updates of the plugin's config GUI elements.

= Also see =

* [[Plugin Auto-Uninstall]]

[[Category:Plugin Development]]

Plugin Autoinstall

2011-03-13T21:08:42Z

Roccivic: updated plugin dependecy and version control

= Introduction =

Geeklog 1.6 brings two important changes regarding installation of plugins:

* Plugins can be installed by uploading their tarball (from Geeklog's Plugins Admin panel)
* Plugins can be bundled / unbundled by simply adding / removing their respective directories to / from the Geeklog tarball

In both of these scenarios, Geeklog needs a way to automatically run the install procedure for such a plugin.

The problem with the plugin install scripts used until now are that they were mainly aimed at being run by a human and that they also check permissions that simply may not be set when the install is done (e.g. when running Geeklog's install script).

The solution proposed here is the inclusion of a new file, <tt>autoinstall.php</tt> into every plugin that implements up to 4 new API functions (3 of which are optional).

= autoinstall.php =

The file <tt>autoinstall.php</tt> is to be located in the plugin's main directory, i.e. in the same directory as its <tt>functions.inc</tt> file:

<pre>/path/to/geeklog/plugins/
foo/
functions.inc
autoinstall.php
staticpages/
functions.inc
autoinstall.php
...</pre>

Plugins that ship with an <tt>autoinstall.php</tt> file won't need to provide the "traditional" install script (<tt>admin/plugins/foo/install.php</tt>) unless they want to be backward-compatible with Geeklog releases prior to 1.6.

== plugin_autoinstall_ ==

This is the most important and mandatory API function to implement in <tt>autoinstall.php</tt>:

<pre>function plugin_autoinstall_foo($pi_name)
{
$pi_name = 'foo';
$pi_display_name = 'Foo';
$pi_admin = $pi_display_name . ' Admin';

$info = array(
'pi_name' => $pi_name,
'pi_display_name' => $pi_display_name,
'pi_version' => '1.0.0',
'pi_gl_version' => '1.6.0',
'pi_homepage' => 'http://www.example.com/'
);

$groups = array(
$pi_admin => 'Has full access to ' . $pi_display_name . ' features'
);

$features = array(
$pi_name . '.edit' => 'Access to ' . $pi_display_name . ' editor'
);

$mappings = array(
$pi_name . '.edit' => array($pi_admin)
);

$tables = array(
'foo'
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables
);

return $inst_parms;
}</pre>

If you've written a Geeklog plugin before, the data provided by this function should look familiar.

The <code>$info</code> array provides the information that goes into the plugin's entry in the <tt>gl_plugins</tt> table. The only addition here is the <code>$pi_display_name</code> entry, so that we can use a nicely formatted name to present to the user instead of having to refer to the plugin by its internal and possibly abbreviated name (<code>$pi_name</code>).

<code>$groups</code> and <code>$features</code> simply list all the groups and features (permissions) that the plugin would like to introduce. Geeklog will create those automatically for the plugin, using the <code>$mappings</code>. <code>$mappings</code> defines which permissions to assign to which of the new groups.

The <code>$tables</code> array obviously lists all the table names used by the plugin (note that the names are given without the <code>$_DB_table_prefix</code>). Geeklog will add these tables names (with the proper prefix) to the global <code>$_TABLES</code> array during the install. The plugin will still have to make sure they are known after the install, e.g. by defining them in its <tt>functions.inc</tt> file.

Finally, all these arrays are wrapped into another array and returned from the autoinstall function.

With the exception of the <code>$info</code> array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide <code>$groups</code> or <code>$tables</code> entries.

In case of an error during the install, Geeklog will also use this information to attempt a cleanup of the database, i.e. remove groups, permissions, etc.

'''Plugin dependencies and version control'''

Since Geeklog 1.8.0, a new and optional array, $requires, is available. It must contain dependency information for a plugin.
You can make a requirement for a particular range of versions of Geeklog, databases and other plugins.
Each dependency is stored inside this array as another array.

The minimal usage is as follows:
<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and does not need a databases to function.
array('plugin' => 'someplugin')
);
...
</pre>

<pre>
...
$requires= array(
// This plugin requires another plugin, 'someplugin', and supports MySQL and PgSQL databases.
array('plugin' => 'someplugin'),
array('db' => 'mysql'),
array('db' => 'pgsql')
);
...
</pre>

You can define any particular range of versions as the requirements for your plugin by adding the 'version' and 'operator' indeces to the arrays. Here's a more complex example:
<pre>
...

$requires= array(
// This plugin requires a version greater than or equal to 1.0.0 of 'someplugin' (The default 'operator' is '>=')
array('plugin' => 'someplugin',
'version' => '1.0.0'),

// This plugin also requires a version greater than 1.0.0 of 'someotherplugin'
array('plugin' => 'someotherplugin',
'version' => '1.0.0',
'operator' => '>'),

// Multiple dependencies are allowed for the same parent plugin
// The below line ensures that only 'someplugin' with version less than 2.0.0 is used
array('plugin' => 'someotherplugin',
'version' => '2.0.0',
'operator' => '<'),

// You can also require a particular range of versions of geeklog
array('core' => 'geeklog',
'version' => '1.8.0'),

// You must require either all or none of the databases that your plugin supports
// Or you might lock out some of the capabilities of your plugin
array('db' => 'mysql'),
array('db' => 'mssql', 'version' => '9.0'), // At least SQL Server 2005
array('db' => 'pgsql', 'version' => '7.3', 'operator' => '>')
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables,
'requires' => $requires // Add the dependency information to the installation parameters here
);

...</pre>

'''Note:''' Expect this function to be called more than once during installation. Also, the fact that the function is being called at all does not necessarily mean that the plugin will actually be installed.

== plugin_postinstall_ ==

Geeklog, armed with the information provided by the <code>plugin_autoinstall_</code> function, will take care of moving the plugin's files into their 3 standard locations, create the tables, the groups, and permissions. For any additional steps that need to be performed during installation, the <code>plugin_postinstall_</code> function will be called:

<pre>function plugin_postinstall_foo($pi_name)</pre>

At this point, all the files are already in their correct place, the groups and permissions have been added and the plugin has been registered with Geeklog (i.e. has been added to the <tt>gl_plugins</tt> table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.

== plugin_compatible_with_this_version_ ==

The very first function from <tt>autoinstall.php</tt> that Geeklog attempts to call is <code>plugin_compatible_with_this_version_</code>. Here, the plugin can check if it's compatible with the current Geeklog version. Since this function was only introduced in Geeklog 1.6.0, you can assume this to be the minimum version.

<pre>function plugin_compatible_with_this_version_foo($pi_name)</pre>

The function should return <code>false</code> when the plugin requires a more recent Geeklog version. Return <code>true</code> if installation on the current Geeklog version is okay.

If you would like to rely on Geeklog's "Plugin dependencies and version control" feature for ensuring that all required plugin are available, you must ensure that the user has at least version 1.8.0 of Geeklog. This can be accomplished with the following code snippet:

<pre>function plugin_compatible_with_this_version_foo($pi_name) {
if (function_exists('PLG_resolveDependencies')) {
return true;
} else {
COM_errorLog('Plugin "foo" requires at least Geeklog 1.8.0, but you are running an older version.');
return false;
}
}</pre>

== plugin_load_configuration_ ==

This function only needs to be implemented by plugins that use the [[PluginConfiguration|Configuration GUI]]. A typical implementation would look like this:

<pre>function plugin_load_configuration_foo($pi_name)
{
global $_CONF;

$base_path = $_CONF['path'] . 'plugins/' . $pi_name . '/';

require_once $_CONF['path_system'] . 'classes/config.class.php';
require_once $base_path . 'install_defaults.php';

return plugin_initconfig_foo();
}</pre>

Where the <code>plugin_initconfig_foo</code> function is implemented in a <tt>install_defaults.php</tt> file, that handles creation and updates of the plugin's config GUI elements.

= Also see =

* [[Plugin Auto-Uninstall]]

[[Category:Plugin Development]]

OAuth

2011-02-25T13:45:51Z

Roccivic: /* OAuth Login Methods */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn and Twitter via OAuth. For each of these three login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0 is supported (OAuth 2.0 is still in development).

== OAuth Login Methods ==

General review...

=== Facebook ===

Access Facebook 'Create an Application' page, and input form. 
http://developers.facebook.com/setup/

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'. 
https://www.linkedin.com/secure/developer

=== Twitter ===
Access 'Applications Using Twitter' page and click 'Register a new application'. 
https://twitter.com/apps 
Application Type: Select 'Browser' 
Callback URL: Input URL same as Website 
Default Access type: Select 'Read & Write' 
Use Twitter for login: Check 

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

File:OAuth-login.png

2011-02-24T00:04:57Z

Roccivic: uploaded a new version of "Image:OAuth-login.png": New OAuth buttons.

Shows the login screen when OAuth is enabled.

OAuth

2011-02-12T00:06:18Z

Roccivic:

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn and Twitter via OAuth. For each of these three login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0 is supported (OAuth 2.0 is still in development).

== OAuth Login Methods ==

General review...

=== Facebook ===

Access Facebook 'Create an Application' page, and input form.
http://developers.facebook.com/setup/

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.
https://www.linkedin.com/secure/developer

=== Twitter ===
Access 'Applications Using Twitter' page and click 'Register a new application »'.
https://twitter.com/apps

Application Type: Select 'Browser'
Callback URL: Input URL same as Website
Default Access type: Select 'Read & Write'
Use Twitter for login: Check

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

File:OAuth-login.png

2011-02-11T23:54:05Z

Roccivic: Shows the login screen when OAuth is enabled.

Shows the login screen when OAuth is enabled.

Plugin Autoinstall

2011-02-06T14:40:06Z

Roccivic: better code snippet

= Introduction =

Geeklog 1.6 brings two important changes regarding installation of plugins:

* Plugins can be installed by uploading their tarball (from Geeklog's Plugins Admin panel)
* Plugins can be bundled / unbundled by simply adding / removing their respective directories to / from the Geeklog tarball

In both of these scenarios, Geeklog needs a way to automatically run the install procedure for such a plugin.

The problem with the plugin install scripts used until now are that they were mainly aimed at being run by a human and that they also check permissions that simply may not be set when the install is done (e.g. when running Geeklog's install script).

The solution proposed here is the inclusion of a new file, <tt>autoinstall.php</tt> into every plugin that implements up to 4 new API functions (3 of which are optional).

= autoinstall.php =

The file <tt>autoinstall.php</tt> is to be located in the plugin's main directory, i.e. in the same directory as its <tt>functions.inc</tt> file:

<pre>/path/to/geeklog/plugins/
foo/
functions.inc
autoinstall.php
staticpages/
functions.inc
autoinstall.php
...</pre>

Plugins that ship with an <tt>autoinstall.php</tt> file won't need to provide the "traditional" install script (<tt>admin/plugins/foo/install.php</tt>) unless they want to be backward-compatible with Geeklog releases prior to 1.6.

== plugin_autoinstall_ ==

This is the most important and mandatory API function to implement in <tt>autoinstall.php</tt>:

<pre>function plugin_autoinstall_foo($pi_name)
{
$pi_name = 'foo';
$pi_display_name = 'Foo';
$pi_admin = $pi_display_name . ' Admin';

$info = array(
'pi_name' => $pi_name,
'pi_display_name' => $pi_display_name,
'pi_version' => '1.0.0',
'pi_gl_version' => '1.6.0',
'pi_homepage' => 'http://www.example.com/'
);

$groups = array(
$pi_admin => 'Has full access to ' . $pi_display_name . ' features'
);

$features = array(
$pi_name . '.edit' => 'Access to ' . $pi_display_name . ' editor'
);

$mappings = array(
$pi_name . '.edit' => array($pi_admin)
);

$tables = array(
'foo'
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables
);

return $inst_parms;
}</pre>

If you've written a Geeklog plugin before, the data provided by this function should look familiar.

The <code>$info</code> array provides the information that goes into the plugin's entry in the <tt>gl_plugins</tt> table. The only addition here is the <code>$pi_display_name</code> entry, so that we can use a nicely formatted name to present to the user instead of having to refer to the plugin by its internal and possibly abbreviated name (<code>$pi_name</code>).

<code>$groups</code> and <code>$features</code> simply list all the groups and features (permissions) that the plugin would like to introduce. Geeklog will create those automatically for the plugin, using the <code>$mappings</code>. <code>$mappings</code> defines which permissions to assign to which of the new groups.

The <code>$tables</code> array obviously lists all the table names used by the plugin (note that the names are given without the <code>$_DB_table_prefix</code>). Geeklog will add these tables names (with the proper prefix) to the global <code>$_TABLES</code> array during the install. The plugin will still have to make sure they are known after the install, e.g. by defining them in its <tt>functions.inc</tt> file.

'''Plugin dependencies and version control'''

Since Geeklog 1.8.0, a new and optional array, $requires, that can contain dependency information for a plugin. Each dependency is stored inside this array as another array. Here's an example:
<pre>
...

$requires= array(
// This plugin requires a version greater than 1.0.0 of 'someplugin'
array('name' => 'someplugin', 'version' => '1.0.0', 'operator' => '>'),

// The default 'operator' is '>='
// This plugin also requires a version greater than or equal to 1.0.0 of 'someotherplugin'
array('name' => 'someotherplugin', 'version' => '1.0.0'),

// Multiple dependencies are allowed for the same parent plugin
// The below line ensures that only 'someplugin' with version less than 2.0.0 is used
array('name' => 'someotherplugin', 'version' => '2.0.0', 'operator' => '<')
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables,
'requires' => $requires
);

...</pre>

Finally, all these arrays are wrapped into another array and returned from the autoinstall function.

With the exception of the <code>$info</code> array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide <code>$groups</code> or <code>$tables</code> entries.

In case of an error during the install, Geeklog will also use this information to attempt a cleanup of the database, i.e. remove groups, permissions, etc.

'''Note:''' Expect this function to be called more than once during installation. Also, the fact that the function is being called at all does not necessarily mean that the plugin will actually be installed.

== plugin_postinstall_ ==

Geeklog, armed with the information provided by the <code>plugin_autoinstall_</code> function, will take care of moving the plugin's files into their 3 standard locations, create the tables, the groups, and permissions. For any additional steps that need to be performed during installation, the <code>plugin_postinstall_</code> function will be called:

<pre>function plugin_postinstall_foo($pi_name)</pre>

At this point, all the files are already in their correct place, the groups and permissions have been added and the plugin has been registered with Geeklog (i.e. has been added to the <tt>gl_plugins</tt> table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.

== plugin_compatible_with_this_version_ ==

The very first function from <tt>autoinstall.php</tt> that Geeklog attempts to call is <code>plugin_compatible_with_this_version_</code>. Here, the plugin can check if it's compatible with the current Geeklog version. Since this function was only introduced in Geeklog 1.6.0, you can assume this to be the minimum version.

<pre>function plugin_compatible_with_this_version_foo($pi_name)</pre>

The function should return <code>false</code> when the plugin requires a more recent Geeklog version. Return <code>true</code> if installation on the current Geeklog version is okay.

If you would like to rely on Geeklog's "Plugin dependencies and version control" feature for ensuring that all required plugin are available, you must ensure that the user has at least version 1.8.0 of Geeklog. This can be accomplished with the following code snippet:

<pre>function plugin_compatible_with_this_version_foo($pi_name) {
if (function_exists('PLG_resolveDependencies')) {
return true;
} else {
COM_errorLog('Plugin "foo" requires at least Geeklog 1.8.0, but you are running an older version.');
return false;
}
}</pre>

== plugin_load_configuration_ ==

This function only needs to be implemented by plugins that use the [[PluginConfiguration|Configuration GUI]]. A typical implementation would look like this:

<pre>function plugin_load_configuration_foo($pi_name)
{
global $_CONF;

$base_path = $_CONF['path'] . 'plugins/' . $pi_name . '/';

require_once $_CONF['path_system'] . 'classes/config.class.php';
require_once $base_path . 'install_defaults.php';

return plugin_initconfig_foo();
}</pre>

Where the <code>plugin_initconfig_foo</code> function is implemented in a <tt>install_defaults.php</tt> file, that handles creation and updates of the plugin's config GUI elements.

= Also see =

* [[Plugin Auto-Uninstall]]

[[Category:Plugin Development]]

Plugin Autoinstall

2011-02-06T14:39:02Z

Roccivic: Added "Plugin dependencies and version control" feature information

= Introduction =

Geeklog 1.6 brings two important changes regarding installation of plugins:

* Plugins can be installed by uploading their tarball (from Geeklog's Plugins Admin panel)
* Plugins can be bundled / unbundled by simply adding / removing their respective directories to / from the Geeklog tarball

In both of these scenarios, Geeklog needs a way to automatically run the install procedure for such a plugin.

The problem with the plugin install scripts used until now are that they were mainly aimed at being run by a human and that they also check permissions that simply may not be set when the install is done (e.g. when running Geeklog's install script).

The solution proposed here is the inclusion of a new file, <tt>autoinstall.php</tt> into every plugin that implements up to 4 new API functions (3 of which are optional).

= autoinstall.php =

The file <tt>autoinstall.php</tt> is to be located in the plugin's main directory, i.e. in the same directory as its <tt>functions.inc</tt> file:

<pre>/path/to/geeklog/plugins/
foo/
functions.inc
autoinstall.php
staticpages/
functions.inc
autoinstall.php
...</pre>

Plugins that ship with an <tt>autoinstall.php</tt> file won't need to provide the "traditional" install script (<tt>admin/plugins/foo/install.php</tt>) unless they want to be backward-compatible with Geeklog releases prior to 1.6.

== plugin_autoinstall_ ==

This is the most important and mandatory API function to implement in <tt>autoinstall.php</tt>:

<pre>function plugin_autoinstall_foo($pi_name)
{
$pi_name = 'foo';
$pi_display_name = 'Foo';
$pi_admin = $pi_display_name . ' Admin';

$info = array(
'pi_name' => $pi_name,
'pi_display_name' => $pi_display_name,
'pi_version' => '1.0.0',
'pi_gl_version' => '1.6.0',
'pi_homepage' => 'http://www.example.com/'
);

$groups = array(
$pi_admin => 'Has full access to ' . $pi_display_name . ' features'
);

$features = array(
$pi_name . '.edit' => 'Access to ' . $pi_display_name . ' editor'
);

$mappings = array(
$pi_name . '.edit' => array($pi_admin)
);

$tables = array(
'foo'
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables
);

return $inst_parms;
}</pre>

If you've written a Geeklog plugin before, the data provided by this function should look familiar.

The <code>$info</code> array provides the information that goes into the plugin's entry in the <tt>gl_plugins</tt> table. The only addition here is the <code>$pi_display_name</code> entry, so that we can use a nicely formatted name to present to the user instead of having to refer to the plugin by its internal and possibly abbreviated name (<code>$pi_name</code>).

<code>$groups</code> and <code>$features</code> simply list all the groups and features (permissions) that the plugin would like to introduce. Geeklog will create those automatically for the plugin, using the <code>$mappings</code>. <code>$mappings</code> defines which permissions to assign to which of the new groups.

The <code>$tables</code> array obviously lists all the table names used by the plugin (note that the names are given without the <code>$_DB_table_prefix</code>). Geeklog will add these tables names (with the proper prefix) to the global <code>$_TABLES</code> array during the install. The plugin will still have to make sure they are known after the install, e.g. by defining them in its <tt>functions.inc</tt> file.

'''Plugin dependencies and version control'''

Since Geeklog 1.8.0, a new and optional array, $requires, that can contain dependency information for a plugin. Each dependency is stored inside this array as another array. Here's an example:
<pre>
...

$requires= array(
// This plugin requires a version greater than 1.0.0 of 'someplugin'
array('name' => 'someplugin', 'version' => '1.0.0', 'operator' => '>'),

// The default 'operator' is '>='
// This plugin also requires a version greater than or equal to 1.0.0 of 'someotherplugin'
array('name' => 'someotherplugin', 'version' => '1.0.0'),

// Multiple dependencies are allowed for the same parent plugin
// The below line ensures that only 'someplugin' with version less than 2.0.0 is used
array('name' => 'someotherplugin', 'version' => '2.0.0', 'operator' => '<')
);

$inst_parms = array(
'info' => $info,
'groups' => $groups,
'features' => $features,
'mappings' => $mappings,
'tables' => $tables,
'requires' => $requires
);

...</pre>

Finally, all these arrays are wrapped into another array and returned from the autoinstall function.

With the exception of the <code>$info</code> array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide <code>$groups</code> or <code>$tables</code> entries.

In case of an error during the install, Geeklog will also use this information to attempt a cleanup of the database, i.e. remove groups, permissions, etc.

'''Note:''' Expect this function to be called more than once during installation. Also, the fact that the function is being called at all does not necessarily mean that the plugin will actually be installed.

== plugin_postinstall_ ==

Geeklog, armed with the information provided by the <code>plugin_autoinstall_</code> function, will take care of moving the plugin's files into their 3 standard locations, create the tables, the groups, and permissions. For any additional steps that need to be performed during installation, the <code>plugin_postinstall_</code> function will be called:

<pre>function plugin_postinstall_foo($pi_name)</pre>

At this point, all the files are already in their correct place, the groups and permissions have been added and the plugin has been registered with Geeklog (i.e. has been added to the <tt>gl_plugins</tt> table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.

== plugin_compatible_with_this_version_ ==

The very first function from <tt>autoinstall.php</tt> that Geeklog attempts to call is <code>plugin_compatible_with_this_version_</code>. Here, the plugin can check if it's compatible with the current Geeklog version. Since this function was only introduced in Geeklog 1.6.0, you can assume this to be the minimum version.

<pre>function plugin_compatible_with_this_version_foo($pi_name)</pre>

The function should return <code>false</code> when the plugin requires a more recent Geeklog version. Return <code>true</code> if installation on the current Geeklog version is okay.

If you would like to rely on Geeklog's "Plugin dependencies and version control" feature for ensuring that all required plugin are available, you must ensure that the user has at least version 1.8.0 of Geeklog. This can be accomplished with the following code snippet:

<pre>function plugin_compatible_with_this_version_foo($pi_name) {
if (!function_exists('PLG_resolveDependencies')) {
COM_errorLog('Plugin "foo" requires at least Geeklog 1.8.0, but you are running an older version.');
return false;
} else {
return true;
}
}</pre>

== plugin_load_configuration_ ==

This function only needs to be implemented by plugins that use the [[PluginConfiguration|Configuration GUI]]. A typical implementation would look like this:

<pre>function plugin_load_configuration_foo($pi_name)
{
global $_CONF;

$base_path = $_CONF['path'] . 'plugins/' . $pi_name . '/';

require_once $_CONF['path_system'] . 'classes/config.class.php';
require_once $base_path . 'install_defaults.php';

return plugin_initconfig_foo();
}</pre>

Where the <code>plugin_initconfig_foo</code> function is implemented in a <tt>install_defaults.php</tt> file, that handles creation and updates of the plugin's config GUI elements.

= Also see =

* [[Plugin Auto-Uninstall]]

[[Category:Plugin Development]]