Edgewall Software

Version 3 (modified by anonymous, 13 years ago) ( diff )

—

Extension Point : IAdminPanelProvider

InterfaceIAdminPanelProviderSince0.11
Moduletrac.adminSourceapi.py​

The IAdminPanelProvider allows adding panels to the TracAdmin web interface (an updated version of the WebAdmin plugin).

Purpose

Trac provides a web interface to allow users with TRAC_ADMIN permission to configure and customize Trac. Plugins can participate in this system by implementing IAdminPanelProvider. This allows a unified web UI where all settings are configured in the same place, the admin tab.

When an admin activates the admin tab, all implementations are called to provide any implemented panels, which are shown as menu options. When the user activates a panel the respective implementation is called to render the selected panel.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The implementation has to render a panel by returning a template file name and a data dictionary to be used by that template. (See ITemplateProvider and IRequestHandler)

The panel template should <xi:include href="admin.html" /> to provide the consistent common UI to all admin panels.

How admin configuration settings are stored depends on the use case. Typical implementations store TracIni settings or database table entries.

Examples

The following example provides a simple admin panel for configuring some query settings. 

from trac.core import *
from trac.admin import IAdminPanelProvider
from trac.web.chrome import ITemplateProvider, add_notice, add_warning
from trac.util.text import exception_to_unicode

class QueryAdminPanel(Component):

    implements(IAdminPanelProvider)

    # IAdminPanelProvidermethods

    def get_admin_panels(self, req):
        if 'TRAC_ADMIN' in req.perm:
            yield ('ticket', _('Ticket System'), 'query', _('Query Settings'))

    def render_admin_panel(self, req, cat, page, version):
        req.perm.require('TRAC_ADMIN')
        options = ('default_anonymous_query', 'default_query', 'ticketlink_query')
        if req.method == 'POST':
            for option in options:
                self.config.set('query', option, req.args.get(option))
            try:
                self.config.save()
                add_notice(req, _('Your changes have been saved.'))
            except Exception, e:
                self.log.error('Error writing to trac.ini: %s', exception_to_unicode(e))
                add_warning(req, _('Error writing to trac.ini, make sure it is '
                                   'writable by the web server. Your changes have '
                                   'not been saved.'))
            req.redirect(req.href.admin(cat, page))

        return 'admin_query.html', dict((option, self.config.get('query', option))
                                        for option in options)
    
    # ITemplateProvider methods
    # Used to add the plugin's templates and htdocs 
    def get_templates_dirs(self):
        from pkg_resources import resource_filename
        return [resource_filename(__name__, 'templates')]

The accompanying admin_query.html: 

<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/"
      xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="admin.html" />
  <head>
    <title>Query</title>
  </head>
  <body>
    <h2>Query Settings</h2>
    <form class="mod" id="modbasic" method="post" action="">
      <fieldset>
        <legend>Default Queries</legend>
        <div class="field">
          <label>Default query for anonymous users:<br />
            <input type="text" name="default_anonymous_query" value="${default_anonymous_query}" />
          </label>
        </div>
        <div class="field">
          <label>Default query for authenticated users:<br />
            <input type="text" name="default_query" value="${default_query}" />
          </label>
        </div>
        <div class="field">
          <label>Base query to be used when linkifying values of ticket fields:<br />
            <input type="text" name="ticketlink_query" value="${ticketlink_query}" />
          </label>
        </div>
      </fieldset>
      <div class="buttons">
        <input type="submit" value="${_('Apply changes')}" />
      </div>
    </form>
  </body>
</html>

Available Implementations

Additional Information and References

Note: See TracWiki for help on using the wiki.