-DEBIAN GFORGE PLUGINS HOWTO
+FUSIONFORGE PLUGINS HOWTO
--------------------------------
-Here is a short HOWTO explaining how plugins work in Debian
-GForge, and how to make a new one.
+Here is a short HOWTO explaining how plugins work, and how to make
+a new one.
It was written by Roland Mas <lolando@debian.org>.
| )
`----
+TODO: add plugins_persistence, group_plugin_persistence, user_plugin_persistence
+
"plugins" lists the installed plugins, with the numeric id, the
string handle (say, "acmetimetracker") and a description.
top menu (after: Login, Logout, My Account).
See plugin online_help for example of use.
+ Hook Name : htmlhead
+ Locations : www/include/Layout.class.php (& derived classes)
+ Description: Used to allow plugins to include code in the <head>.
+ See plugin message for example of use.
+
Hook Name : javascript
Locations : www/include/Layout.class.php
www/include/LayoutSF.class.php
Description: Provides a place to add inline Javascript into the page.
- The output of the hook should be pure Javascript, as it will
+ The output (in $params['return']) of the hook should be pure Javascript, as it will
be placed within an existing <script> block.
[TODO: The output of the hook appears after the closing SGML comment marker
and before the closing </script> element. Is this what is really indended?]
a <li> block and will appear on the Site Admin page in the
Site Utilities list.
+ Hook Name : site_admin_project_maintenance_hook
+ Locations : www/admin/index.php
+ Description: Use this to provide a link to the project maintenance pages
+ for your plugin. The hook should obey the plugin_hook_by_reference()
+ protocol and concatenate a <li> HTML block to params['result'] so
+ that it can appear in the "Plugins Project Maintenance" subsection
+
+ Hook Name : site_admin_user_maintenance_hook
+ Locations : www/admin/index.php
+ Description: Use this to provide a link to the user maintenance pages
+ for your plugin. The hook should obey the plugin_hook_by_reference()
+ protocol and concatenate a <li> HTML block to params['result'] so
+ that it can appear in the "Plugins User Maintenance" subsection
+
Hook Name : task_extra_detail
Parameters : task_id - The numeric ID for a task
Locations : www/pm/detail_task.php
Description: Used to provide plugin specific infos on a group's
public area.
+ Hook Name : user_logo
+ Parameters : user_id, size, content (return value)
+ Locations : common/include/utils.php
+ Description: plugin_hook_by_reference hook used to provide a user
+ picture in params['content'] (see gravatar plugin for instance)
+
+ Hook Name : user_link_with_tooltip
+ Parameters : username, user_id, user_link (return value)
+ Locations : common/include/utils.php
+ Description: plugin_hook_by_reference hook used to replace util_display_user()
+ default behaviour, returns value in params['user_link']
+ (see oslc plugin for instance)
+
+TODO : document Auth plugins :
+
+ Hook Name : display_auth_form
+ Parameters : return_to
+ Locations : www/include/login-form.php
+ Description: returns a login dialog and/or a redirect URL :
+ it should return an HTML dialog appened to passed $params['html_snippets']
+ it may return a redirection URL appened to $params['transparent_redirect_urls']
+
+ Hook Name : check_auth_session
+ Parameters : auth_token ??
+ Locations : common/include/session.php
+ Description: is there a valid session?
+ it returns a ??? appened to passed $params['results'] :FORGE_AUTH_AUTHORITATIVE_ACCEPT, FORGE_AUTH_AUTHORITATIVE_REJECT
+
+ Hook Name : fetch_authenticated_user
+ Parameters : ??
+ Locations : common/include/session.php
+ Description: what GFUser is logged in?
+ it returns a user object in passed $params['results']
+
+ Hook Name : widgets
+ Parameters : $params['owner_type'] == WidgetLayoutManager::OWNER_TYPE_GROUP or WidgetLayoutManager::OWNER_TYPE_USER
+ Description: appends to $params['fusionforge_widgets'] (or 'codendi_widgets') names
+ of widgets it provides depending on the project home or user home context
+
+ Hook Name : widget_instance
+ Parameters : $params['widget'] provides the widget name
+ Description: returns in $params['instance'] an instance of the new Widget subclass
+
+ Hook Name : script_accepted_types
+ Parameters : $params['script'] == 'project_home' or 'user_home' depending on whether providing alternate accept types for such pages
+ Description: appends to $params['accepted_types'] alternate HTTP Accept Content-types supported by a plugin for the
+ /projects or /users/ pages rendered through content-negociation
+
+ Hook Name : content_negociated_project_home
+ Parameters : $params['accept'] provides the content-type to be rendered, $params['groupname'] the project name, $params['group_id'] the project ID
+ Description: returns in $params['content'] an alternate content for /projects/ page and
+ in $params['content_type'] the actual content-type to return
+
+ Hook Name : content_negociated_user_home
+ Parameters : $params['accept'] provides the content-type to be rendered, $params['username'] the user name
+ Description: returns in $params['content'] an alternate content for /users/ page and
+ in $params['content_type'] the actual content-type to return
+
+ Hook Name : project_rdf_metadata
+ Parameters : $params['prefixes'] : already used RDF prefixes in the form URL => shortname, $params['in_Resource'] : already constructed ARC2_Resource instances (read-only)
+ Description: returns in $params['prefixes'] added prefixes, and in the array $params['out_Resources'] new ARC2_Resources including new triples to be included in the project's DOAP description
+
+ Hook Name : role_adduser
+ Parameters : $params['user'] : user added to the role, $params['role'] : role added to the user
+ Locations : common/include/RBAC.php
+ Description: Called when a role is added to an user.
+
+ Hook Name : role_removeuser
+ Parameters : $params['user'] : user removed to the role, $params['role'] : role removed to the user
+ Locations : common/include/RBAC.php
+ Description: Called when a role is removed to an user.
+
+ Hook Name : alt_representations
+ Parameters : $params['script_name'] contains the SCRIPT_NAME (filtered to work only on /projects or /users for the moment)
+ Description: returns alternate representations for a particular page in $params['results'] which is populated by the hook users
+
+TODO (nerville) : document display_hierarchy
+TODO (lolando ?) : document role_normalize, role_translate_strings, role_has_permission, role_get_setting, list_roles_by_permission
+TODO : document project_link_with_tooltip
+
-- Roland Mas <lolando@debian.org>