Edgewall Software

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 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)

The accompanying admin_query.html template (provided by an appropriate ITemplateProvider implementation): 

<!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

Last modified 13 years ago Last modified on Aug 7, 2011, 10:46:04 AM
Note: See TracWiki for help on using the wiki.