User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:addson_requirements

This is an old revision of the document!


Mantis Add-Ons Requirements

  • Author: Victor Boctor
  • Status: In Progress

Introduction

Mantis currently supports some extensibility features like custom fields, custom functions, custom constants, and custom strings. These has proven to be useful features that allowed Mantis users to tweak their own installations without having to change Mantis code base and hence making the upgrade experience much easier. The aim of Mantis Add-ons support is to take this to the next level and enable users to do more powerful additions to Mantis and be able to make these publicly available to other users. Some of the add-ons will be distributed with Mantis and others will be available through Mantis website / bugtracker.

Types of Plug-in

  • Display Filters - Provides the ability to pre-process strings before they outputted to the web page. This can be used to implement features like the ones built-in Mantis to link to issues, issue notes and cvs web. This is where # + 123 is converted to a hyperlink to issue number 123.
  • Group Action - Provides the ability to process a set of issues that have been selected from the View Issues page and based on user's input process such issues in a custom way.
  • Issue Action - Ability to add an action button to the Issue View page, this is like the Monitor and Delete buttons.
  • Reports - Users should be able to easily develop extra reports
  • Extensions - Ability to implement a Mantis extension which cuts across all different areas of Mantis, extra fields, extra reporting, configuration, reports, menu options, etc.

Plug-ins Support Infrastructure

  • Ability to detect all plug-ins in the Mantis directory structure.
  • From the manage plug-ins page, allow administrators (configurable threshold) to install / un-install an add-on.
  • Keep track of the installed add-ons and make sure to provide them with the needed integration points.
  • Extend the database scheme upgrade script to support modules.
  • Detailed documentation about how to implement Mantis plug-ins.

Information about a plugin

  • Name
  • Publisher (e.g. Mantis Group)
  • Publisher's Website (e.g. http://www.mantisbt.org)
  • Description
  • Status (stable, beta, etc?)
  • Creation Date
  • Mantis Minimum Version
  • PHP Minimum Version
  • PHP Maximum Version (?)
  • RequiredModules (array)

We can add support for dependencies on DB type, DB version, web server, etc. However, ideally we should target to reduce such dependencies when possible.

Directory Structure

mantis/
  admin/
  core/
  lang/
  modules/
    css/
      *.css
    images/
      logo.jpg (some plugins may have logos, file name is configurable)
    core/
      functions_inc.php
    javascript/
      *.js
    doc/
      readme.html
    lang/
      strings_english.txt
    pages/
      (new pages - included from module_page.php based on module name and action)
    #modulename#_constants_inc.php
    #modulename#_defaults_inc.php
    #modulename#_inc.php
  • #modulename#_inc.php - This file includes the following actions:
    • register in events
    • register necessary css based on current page.
    • register necessary javascript based on current page.
    • register menu options (menu, label_id, url)
    • register string_display_filter
    • register view issues links (e.g. csv, graphs, etc)
    • register view issue links (e.g. Wiki)
    • register the pages to include the plug-in (or ALL).
    • register the pages to exclude the plug-in (or empty array)
    • Support system exclude from pages (e.g. download attachment, module management page, etc)

Configuration Options

  • manage_plugins_threshold.

Note that the plugins are always applied to all projects. It is up to the plugin to scope down its functionality (if necessary).

New Pages

The following pages will allow management of plug-ins and all their related details:

  • manage_modules_page.php: This pages lists all the available modules, their minimum requirements, dependencies, etc. It also allows administrators to the install / uninstall the available plugins.
  • manage_modules_add.php: The action page for installing modules.
  • manage_modules_remove.php: The action page for uninstalling modules.
  • module_page.php: This page takes in the plugin name, action as mandatory parameters. Depending on the “action” there can be other parameters. For example, module_page.php?module=last_visited&action=readme will view the readme of the plugin. The modules folder will have a .htaccess file that blocks direct access to files in the modules tree.

Plug-ins APIs

This is the standard APIs that are used in managing modules and allowing modules to interact with some standard Mantis functionality. In addition to these APIs, the plug-in implementation can use the rest of the APIs like strings_api, etc.

  • module_event - trigger an event with the appropriate parameters.
  • module_event_is_subscribed() - check before doing extra work for the event.
  • module_include_all()
  • module_include_lang()
  • module_include_css()
  • module_include_javascript()
  • module_get_info( $p_module_name );
  • module_install( $p_module_name );
  • module_get_dependencies( $p_module_name )
  • module_can_install( $p_module_name )
  • module_get_depedents( $p_module )
  • module_can_uninstall( $p_module )

Events

Events are integration points that are similar to custom functions, however, they can be handled by one or more of the installed plug-ins. Typically, events take in parameters and do not have a return value.

  • issue created
  • issue updated
  • issue deleted
  • issue viewed
  • issue cloned
  • issue moved
  • issue assigned
  • issue re-assigned
  • issue status changed
  • issue attachment attached
  • issue attachment deleted
  • issue attachment preview
  • user created by administrator
  • user signed up
  • user logged in for first time
  • user pruned
  • user deleted
  • user disabled
  • user authentication failed
  • user logged in
  • user updated
  • user added to project
  • user removed from project
  • cronjob
  • news added
  • news updated
  • news deleted
  • note added
  • note updated
  • note deleted
  • issue monitored
  • issue unmonitored
  • relationship_added
  • relationship_deleted
  • relationship_updated
  • sponsorship_added
  • sponsorship_updated
  • sponsorship_deleted
  • category_added
  • category_updated
  • category_deleted
  • version_added
  • version_updated
  • version_deleted
  • checkin
  • project file attached
  • project file deleted
  • tag created
  • tag updated
  • tag deleted
  • tag attached
  • tag detached
  • user heartbeat (can be used for users online)
  • error (only for php errors, email errors, etc - i.e. system errors).

Output Hooks

Plug-ins should be able to create new pages, however, they should also be able to enrich the content of some of the existing pages. This is through some pre-defined output hooks. Following are the initial set. In the future, it should be easy to add more of these hooks. In each of these pages there can be one or more places where content can be injected.

  • issue view
  • user view
  • project page view
  • my view page
  • below menu (similar to the current location of “last visited”)

Ideas for Plugins

  • notification plugins
    • email plugin
    • twitter pluggin
    • sms pluggin
  • attachment preview
    • files (e.g. images, txt, flash)
    • urls (e.g. youtube)
  • bbcode
  • Issue Action Group (may need a bit of cleanup)
  • Audit Log
  • Issues Last Visited (as a plug-in rather than built-in feature)
  • Email admin on errors
  • Wiki integration?
  • Email Reports: e.g. issues matching filter sent to <myself>
    • created by a user
    • can be public, hence, will trigger for each user
    • min access level
    • max access level
    • for each project?

Feedback

This is still in progress, but you are free to contribute ideas.

First implementation

A first implementation has been written, you can find it here. This implementation does not respect the requirements. You can play with it here, create an account and go to the plugin page (take care this is a real bugtracker, not a demo version).

Respect

  • Ability to detect add-ons.
  • Allow configuration of the add-ons.

Does not respect

  • No install/uninstall script (but plugin can be enable/disabled).
  • Check the requirements.
  • Directory structure not respected:
mantis/
  admin/
  core/
  lang/
  plugins_page.php
  plugins/
    plugin1/
    plugin2/
    plugin3/
      index.php
      info.php
      core/
        functions_api.php
      lang/
        strings_english.txt

What the plugin manager does?

  • It is in charge to load the strings_*.txt file according to the current language
  • It is in charge to allow configuration of the plugin according to the access_level. The configuration page is located into index.php
  • It checks new release of the plugin (optional).
mantisbt/addson_requirements.1189058701.txt.gz · Last modified: 2008/10/29 04:32 (external edit)

Driven by DokuWiki