Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.admin.api.IAdminPanelProvider


Ignore:
Timestamp:
Jun 30, 2011, 9:03:32 PM (11 years ago)
Author:
psuter <petsuter@…>
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.admin.api.IAdminPanelProvider

    v1 v1  
     1== Extension Point : ''IAdminPanelProvider'' ==
     2
     3||'''Interface'''||''IAdminPanelProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IAdminPanelProvider 0.11]||
     4||'''Module'''||''trac.admin''||'''Source'''||[source:trunk/trac/admin/api.py api.py]||
     5
     6The ''IAdminPanelProvider'' allows adding panels to the TracAdmin web interface (an updated version of the WebAdmin plugin).
     7
     8== Purpose ==
     9
     10Trac 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.
     11
     12When 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.
     13
     14== Usage ==
     15
     16Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     17
     18The 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])
     19
     20The panel template should {{{<xi:include href="admin.html" />}}} to provide the consistent common UI to all admin panels.
     21
     22How admin configuration settings are stored depends on the use case. Typical implementations store TracIni settings or database table entries.
     23
     24== Examples ==
     25
     26The following example provides a simple admin panel for configuring some [TracIni#query-section query settings].
     27
     28{{{#!python
     29from trac.core import *
     30from trac.admin import IAdminPanelProvider
     31from trac.web.chrome import add_notice, add_warning
     32from trac.util.text import exception_to_unicode
     33
     34class QueryAdminPanel(Component):
     35
     36    implements(IAdminPanelProvider)
     37
     38    # IAdminPanelProvidermethods
     39
     40    def get_admin_panels(self, req):
     41        if 'TRAC_ADMIN' in req.perm:
     42            yield ('ticket', _('Ticket System'), 'query', _('Query Settings'))
     43
     44    def render_admin_panel(self, req, cat, page, version):
     45        req.perm.require('TRAC_ADMIN')
     46        options = ('default_anonymous_query', 'default_query', 'ticketlink_query')
     47        if req.method == 'POST':
     48            for option in options:
     49                self.config.set('query', option, req.args.get(option))
     50            try:
     51                config.save()
     52                add_notice(req, _('Your changes have been saved.'))
     53            except Exception, e:
     54                self.log.error('Error writing to trac.ini: %s', exception_to_unicode(e))
     55                add_warning(req, _('Error writing to trac.ini, make sure it is '
     56                                   'writable by the web server. Your changes have '
     57                                   'not been saved.'))
     58            req.redirect(req.href.admin(cat, page))
     59
     60        return 'admin_query.html', dict((option, self.config.get('query', option))
     61                                        for option in options)
     62}}}
     63
     64The accompanying ''admin_query.html'':
     65{{{#!xml
     66<!DOCTYPE html
     67    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     68    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
     69<html xmlns="http://www.w3.org/1999/xhtml"
     70      xmlns:py="http://genshi.edgewall.org/"
     71      xmlns:xi="http://www.w3.org/2001/XInclude">
     72  <xi:include href="admin.html" />
     73  <head>
     74    <title>Query</title>
     75  </head>
     76  <body>
     77    <h2>Query Settings</h2>
     78    <form class="mod" id="modbasic" method="post" action="">
     79      <fieldset>
     80        <legend>Default Queries</legend>
     81        <div class="field">
     82          <label>Default query for anonymous users:<br />
     83            <input type="text" name="default_anonymous_query" value="${default_anonymous_query}" />
     84          </label>
     85        </div>
     86        <div class="field">
     87          <label>Default query for authenticated users:<br />
     88            <input type="text" name="default_query" value="${default_query}" />
     89          </label>
     90        </div>
     91        <div class="field">
     92          <label>Base query to be used when linkifying values of ticket fields:<br />
     93            <input type="text" name="ticketlink_query" value="${ticketlink_query}" />
     94          </label>
     95        </div>
     96      </fieldset>
     97      <div class="buttons">
     98        <input type="submit" value="${_('Apply changes')}" />
     99      </div>
     100    </form>
     101  </body>
     102</html>
     103}}}
     104
     105== Available Implementations ==
     106* General
     107 * [source:trunk/trac/admin/web_ui.py#L201 BasicsAdminPanel][[br]]
     108   Provides the ''General - Basic Settings'' panel
     109 * [source:trunk/trac/admin/web_ui.py#L259 LoggingAdminPanel][[br]]
     110   Provides the ''General - Logging'' panel
     111 * [source:trunk/trac/admin/web_ui.py#L343 PermissionAdminPanel][[br]]
     112   Provides the ''General - Permissions'' panel
     113 * [source:trunk/trac/admin/web_ui.py#L429 PluginsAdminPanel][[br]]
     114   Provides the ''General - Plugins'' panel
     115 * [source:trunk/trac/ticket/admin.py#L74 ComponentAdminPanel][[br]]
     116   Provides the ''Ticket System - Components'' panel
     117* Ticket System
     118 * [source:trunk/trac/ticket/admin.py#L228 MilestoneAdminPanel][[br]]
     119   Provides the ''Ticket System - Milestones'' panel
     120 * [source:trunk/trac/ticket/admin.py#L418 VersionAdminPanel][[br]]
     121   Provides the ''Ticket System - Versions'' panel
     122 * [source:trunk/trac/ticket/admin.py#L753 PriorityAdminPanel][[br]]
     123   Provides the ''Ticket System - Priorities'' panel
     124 * [source:trunk/trac/ticket/admin.py#L759 ResolutionAdminPanel][[br]]
     125   Provides the ''Ticket System - Resolutions'' panel
     126 * [source:trunk/trac/ticket/admin.py#L765 SeverityAdminPanel][[br]]
     127   Provides the ''Ticket System - Severities'' panel
     128 * [source:trunk/trac/ticket/admin.py#L771 TicketTypeAdminPanel][[br]]
     129   Provides the ''Ticket System - Ticket Types'' panel
     130* Version Control
     131 * [source:trunk/trac/versioncontrol/admin.py#L163 RepositoryAdminPanel][[br]]
     132   Provides the ''Version Control - Repositories'' panel
     133* In third-party plugins:
     134 * [th:wiki:AccountManagerPlugin/Modules#AccountManagerAdminPage AccountManagerPlugin][[br]]
     135   Defines new panels for managing user accounts.
     136 * [th:wiki:IniAdminPlugin IniAdminPlugin] / [th:wiki:TracIniAdminPanelPlugin TracIniAdminPanelPlugin][[br]]
     137   Advanced implementation with dynamic controls for TracIni settings.
     138
     139== Additional Information and References ==
     140
     141 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.admin.api.IAdminPanelProvider-class.html epydoc]
     142 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_admin.html#trac.admin.IAdminPanelProvider API Reference]
     143 * Originally part of the WebAdmin plugin
     144 * Some similarities to the [[trac.prefs.api.IPreferencePanelProvider]]
     145 * Related tickets:
     146  * [query:status=!closed&component=admin/web admin/web component]
     147  * [query:"?status=!closed&keywords=~web admin" web & admin keywords]
     148  * [query:"?status=!closed&summary=~webadmin" WebAdmin in summary]