== Extension Point : ''IAdminPanelProvider'' ==
||'''Interface'''||''IAdminPanelProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IAdminPanelProvider 0.11]||
||'''Module'''||''trac.admin''||'''Source'''||[source:trunk/trac/admin/api.py api.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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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 [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider ITemplateProvider] and [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IRequestHandler IRequestHandler])
The panel template should {{{}}} 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 [TracIni#query-section query settings].
{{{#!python
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'':
{{{#!xml
Query
Query Settings
}}}
== Available Implementations ==
* General
* [source:trunk/trac/admin/web_ui.py#L201 BasicsAdminPanel][[br]]
Provides the ''General - Basic Settings'' panel
* [source:trunk/trac/admin/web_ui.py#L259 LoggingAdminPanel][[br]]
Provides the ''General - Logging'' panel
* [source:trunk/trac/admin/web_ui.py#L343 PermissionAdminPanel][[br]]
Provides the ''General - Permissions'' panel
* [source:trunk/trac/admin/web_ui.py#L429 PluginsAdminPanel][[br]]
Provides the ''General - Plugins'' panel
* [source:trunk/trac/ticket/admin.py#L74 ComponentAdminPanel][[br]]
Provides the ''Ticket System - Components'' panel
* Ticket System
* [source:trunk/trac/ticket/admin.py#L228 MilestoneAdminPanel][[br]]
Provides the ''Ticket System - Milestones'' panel
* [source:trunk/trac/ticket/admin.py#L418 VersionAdminPanel][[br]]
Provides the ''Ticket System - Versions'' panel
* [source:trunk/trac/ticket/admin.py#L753 PriorityAdminPanel][[br]]
Provides the ''Ticket System - Priorities'' panel
* [source:trunk/trac/ticket/admin.py#L759 ResolutionAdminPanel][[br]]
Provides the ''Ticket System - Resolutions'' panel
* [source:trunk/trac/ticket/admin.py#L765 SeverityAdminPanel][[br]]
Provides the ''Ticket System - Severities'' panel
* [source:trunk/trac/ticket/admin.py#L771 TicketTypeAdminPanel][[br]]
Provides the ''Ticket System - Ticket Types'' panel
* Version Control
* [source:trunk/trac/versioncontrol/admin.py#L163 RepositoryAdminPanel][[br]]
Provides the ''Version Control - Repositories'' panel
* In third-party plugins:
* [th:wiki:AccountManagerPlugin/Modules#AccountManagerAdminPage AccountManagerPlugin][[br]]
Defines new panels for managing user accounts.
* [th:wiki:IniAdminPlugin IniAdminPlugin] / [th:wiki:TracIniAdminPanelPlugin TracIniAdminPanelPlugin][[br]]
Advanced implementation with dynamic controls for TracIni settings.
== Additional Information and References ==
* [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.admin.api.IAdminPanelProvider-class.html epydoc]
* [http://www.edgewall.org/docs/trac-trunk/html/api/trac_admin.html#trac.admin.IAdminPanelProvider API Reference]
* Originally part of the WebAdmin plugin
* Some similarities to the [[trac.prefs.api.IPreferencePanelProvider]]
* Related tickets:
* [query:status=!closed&component=admin/web admin/web component]
* [query:"?status=!closed&keywords=~web admin" web & admin keywords]
* [query:"?status=!closed&summary=~webadmin" WebAdmin in summary]