Difference between revisions of "Plugin Autoinstall"
(added note that the autoinstall function may be called more than once) |
m (missing word) |
||
Line 92: | Line 92: | ||
== plugin_postinstall_ == | == 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 performed during installation, the <code>plugin_postinstall_</code> function will be called: | + | 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> | <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. | 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. |
Revision as of 22:39, 21 February 2009
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, autoinstall.php into every plugin that implements up to 4 new API functions (3 of which are optional).
autoinstall.php
The file autoinstall.php is to be located in the plugin's main directory, i.e. in the same directory as its functions.inc file:
/path/to/geeklog/plugins/ foo/ functions.inc autoinstall.php staticpages/ functions.inc autoinstall.php ...
Plugins that ship with an autoinstall.php file won't need to provide the "traditional" install script (admin/plugins/foo/install.php) 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 autoinstall.php:
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; }
If you've written a Geeklog plugin before, the data provided by this function should look familiar.
The $info
array provides the information that goes into the plugin's entry in the gl_plugins table. The only addition here is the $pi_display_name
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 ($pi_name
).
$groups
and $features
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 $mappings
. $mappings
defines which permissions to assign to which of the new groups.
The $tables
array obviously lists all the table names used by the plugin (note that the names are given without the $_DB_table_prefix
). Geeklog will add these tables names (with the proper prefix) to the global $_TABLES
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 functions.inc file.
Finally, all these arrays are wrapped into another array and returned from the autoinstall function.
With the exception of the $info
array, all of these arrays are optional. Plugins that don't create any groups or tables don't need to provide $groups
or $tables
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 plugin_autoinstall_
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 plugin_postinstall_
function will be called:
function plugin_postinstall_foo($pi_name)
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 gl_plugins table). However, the plugin has not been loaded yet, i.e. you can not rely on any of your plugin's functions being available.