Writing plugins
From ResourceSpace Documentation Wiki
The plug-in architecture is available from version 1.3. To ensure you have all the latest hooks it's recommended you use a checked out working copy of ResourceSpace from Subversion so you can run 'svn update' and regularly receive updates with the latest hooks.
It is strongly recommended that all external modification work is implemented as plugins, so that compatibility with the base code is not broken and your installation can be easily upgraded in the future.
Each plugin must have it's own subfolder in the plugins folder. $plugins is set in config.php, which is an array listing all installed plugins. Installing a plugin should be a two step process for a user (with an optional third step):
- Unzip the plugin into it's own subfolder in the plugins folder
- Add the plugin name to the $plugins array in config.php
- Optionally, configure the plugin using the separate config.php file in the plugin's config folder.
Golden rule for plugin development:
- The above install steps are all that is ever required of the user. That is, no other modifications to RS files should be required. This ensures 100% compatibility with the base at all times.
Contents |
Hooks
Plugins are based around the concept of 'hooks'. Existing ResourceSpace files will call hook functions where they exist within the plugin code.
All pages contain certain base hooks, and each page will also have several hooks that are specific to a page.
For example, the search page may contain a hook named 'toolbar' which is called at the end of the list of links, so a plugin coder could add an additional link to that page. The hook would be created in the file:
plugins/(plugin name)/hooks/search.php
For small and simple plugins, you could place all hook functions in a file named "all.php" which gets included in every page. Larger plugins should use the separate files for each page.
The hook would take the form of a function following the syntax "HookPluginnamePagenameHookname", for example:
function HookMypluginSearchToolbar()
{
# Extra link code goes here
return true;
}
Note the capitalisation on the function name. The plugin name, page name and hook name always start with an upper case letter.
It's also possible to create hooks that trigger on every page using the page name 'all'. So in "all.php" you would add the function "HookMypluginAllInitialise" to create a function for the "initialise" hook present at the top of every page.
Some hooks allow you to creation additional functionality as your code will be called in addition to the existing ResourceSpace code. Other hooks allow you replace existing functionality, as your code will replace any existing ResourceSpace functionality. These are labelled "Replace" and "Addition" in the table below.
For hooks that replace functionality, hooks must return true if the existing functionality is to be replaced. Otherwise it will not be replaced. This means hooks can perform some additional checks (e.g. that the resource is of a certain resource type) before going ahead and replacing functionality.
Hook List
Hooks listed below with page name "All" apply to all pages, that is, a hook exists on ever page with that name.
| Page | Hook name | Description | Replace / Addition | |
|---|---|---|---|---|
| All | Initialise | Called at the beginning of script execution on all pages, after language/plugin declarations but before function declaration and HTML output begins | Addition | |
| All | Headblock | Called in the HTML head block so additional head tags, such as meta, can be added | Addition | |
| All | Bodystart | Called just after the body tag has been declared so additional HTML can be placed at the top of the page | Addition | |
| All | Searchbartoptoolbar | Called on top of SearchBar html. | Addition | |
| All | Headerbottom | Called on bottom of header. | Addition | |
| All | Footerbottom | Called on bottom of footer. | Addition | |
| All | Searchbarbottomtoolbar | Called on bottom of SearchBar html. | Addition | |
| All | toptoolbaradder | Called to add top toolbar menu links (in header.php). | Addition | |
| Search | Renderresultthumb | Called when rendering a search result in thumb mode. | Replace | |
| Search | Rendertitlethumb | Called when rendering the search result title in thumb mode. | Replace | |
| Search | Renderimagethumb | Called when rendering the search result thumbnail in thumb mode. | Replace | |
| Search | Resultsbottomtoolbar | Called when rendering the bottom toolbar (actions on current search). | Addition | |
| Search | Adddisplaymode | Called to render link to new results display mode. | Addition | |
| Search | Customdisplaymode | Called to render resource resutl in custom display mode. | Addition | |
| Collections | Resourceview | Called when rendering the resource into a collection. | Replace | |
| Collections | Processusercommand | Called to answer to a custom user command on collections. | Addition | |
| Collections | prechangecollection | Called before handling "change collection" command. | Addition | |
| Collections | postchangecollection | Called after handling "change collection" command. | Addition | |
| Collections | preaddtocollection | Called before handling "add to collection" command. | Addition | |
| Collections | postaddtocollection | Called after handling "add to collection" command. | Addition | |
| Collections | preremovefromcollection | Called before handling "remove from collection" command. | Addition | |
| Collections | postremovefromcollection | Called after handling "remove from collection" command. | Addition | |
| Collections | preaddsearch | Called before handling "add serach to collection" command. | Addition | |
| Collections | postaddsearch | Called after handling "add search to collection" command. | Addition | |
| Collections | preremovesearch | Called before handling "remove search from collection" command. | Addition | |
| Collections | postremovesearch | Called after handling "remove search from collection" command. | Addition | |
| Collections | preresearch | Called before handling "reaserch" command. | Addition | |
| Collections | postresearch | Called after handling "reasearch" command. | Addition | |
| Collections | thumbsmenu | Replaces the left hand menu in the thumbnail view. | Replace | |
| Collections | nothumbs | Replaces the whole menu in the no-thumbs view. | Replace | |
| View | renderinnerresourceheader | Called when rendering the header of a resource view (inner div html). | Replace | |
| View | renderbeforeresourceview | Called between the header div and the resource div of a resource view. | Addition | |
| View | renderinnerresourceview | Called when rendering the resource view main panel (preview & download options) (inner div html). | Replace | |
| View | renderinnerresourcepreview | Called when rendering the resource preview (inner div html). | Replace | |
| View | renderinnerresourcedownloadspace | Called when rendering the resource download space (inner div html). | Replace | |
| View | renderbeforeresourcedetails | Called before rendering resource details (resource data). | Addition | |
| View | resourceactions | Called before the resource actions so new actions can be added. | Addition | |
| Themes | collectioninfo | Called right after collection name. | Addition | |
| Collection_manage | Addcustomtool | Called to add a custom tool to collection. | Addition | |
| Home | replacehome | Called when rendering the home screen (in between header and footer). | Replace | |
| Delete | custompredeleteresource | Called before deleting a resource. | Replace | |
| Delete | custompostdeleteresource | Called after deleting a resource. | Replace | View |
| Properties | treealter | Called after the System Setup tree is loaded, so parameters can be altered by a plugin. | Addition |
Procedure for adding new hooks
You will no doubt require further hooks when developing a plugin. The procedure is as follows:
- Add the hook(s) to your own code so you can proceed with plugin development.
- Submit the changed file(s) to the Google Groups forum under an existing New Hooks topic (create such a topic if it does not yet exist or has expired). Detail which hooks you have added and where
- The hooks will be added to the latest code in the Subversion repository by one of the developers with write access to Subversion.
- You can then run 'svn update' to fetch the latest code, overwriting your own changed files.
- Document your hooks on this wiki page.
Extending the database with 'dbstruct'
It's possible within a plugin to define additional columns on existing tables that you require, or entirely new tables just for use with your plugin.
Create a file in a subfolder called 'dbstruct' called:
table_(yourtable).txt
If (yourtable) is an existing table then the file should contain only definitions for the columns you wish to add. If it's a new table then you should define all the columns you need. See the existing files in the ResourceSpace dbstruct folder in the root for examples of the required format. The files are simply CSV versions of the results provided from the 'describe (table)' MySQL command.
You can also use 'index_' and 'data_' files to define indices and default data for your tables, exactly as ResourceSpace itself does using the existing dbstruct folder.
A useful naming convention: prefix any tables and columns specific to your plugin with the name of your plugin. This will aid manual database clean-up operations later if your plugin is removed (your tables/columns are not automatically removed when your plugin is deleted).
Function Overrides
It's possible to override an existing function by simply declaring it in either "hooks/all.php" if you want it to be overridden for every page, or "hooks/(pagename).php" to override a function for a specific page only.
When overriding functions it is best to check that the function has not already been declared by a previous plugin first.
As an example, to override the 'do_search' function for all pages add the following to 'hooks/all.php'.
if (!function_exists("do_search"))
{
function do_search($search,$restypes="",$order_by="relevance",$archive=0,$fetchrows=-1)
{
# New function code goes here
}
}
A function check needs to be added to the base code if you plan to do a function override.
Plugin subfolders
Subfolders are as follows (a plugin need only contain the subfolders it requires however). A plugin need not contain all subfolders - just those that need to contain files. A really simple plugin might just have a hook folder containing one file, for example.
A plugin need not contain functionality, it could be purely a visual enhancement. For example by just including a new stylesheet in the 'css' subfolder and some graphics in 'gfx' a simple 'colour theme' plugin could be created that rebrands the system.
- config - contains config.php, the plugin specific settings file
- hooks - contain the hook function files.
- languages - contains plugin specific language files (works as per the existing languages system)
- pages - contains any new PHP pages specific to the plugin
- static - contains any static files required by the plugin (e.g. css, graphics)
- css - place a file in here called 'style.css' and it will automatically be included in all pages.
- dbstruct - database definition CSV files for an additional columns or entirely new tables required.
Suggested additional files in the root folder (all lower case).
- about.txt - a paragraph of text describing the plugin that could be automatically extracted/displayed by a future plugin directory system. Include credits.
- license.txt - your license details
- install.txt - installation instructions.
