| 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 | |
| 6 | The ''IAdminPanelProvider'' allows adding panels to the TracAdmin web interface (an updated version of the WebAdmin plugin). |
| 7 | |
| 8 | == Purpose == |
| 9 | |
| 10 | 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. |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | == Usage == |
| 15 | |
| 16 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| 17 | |
| 18 | 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]) |
| 19 | |
| 20 | The panel template should {{{<xi:include href="admin.html" />}}} to provide the consistent common UI to all admin panels. |
| 21 | |
| 22 | How admin configuration settings are stored depends on the use case. Typical implementations store TracIni settings or database table entries. |
| 23 | |
| 24 | == Examples == |
| 25 | |
| 26 | The following example provides a simple admin panel for configuring some [TracIni#query-section query settings]. |
| 27 | |
| 28 | {{{#!python |
| 29 | from trac.core import * |
| 30 | from trac.admin import IAdminPanelProvider |
| 31 | from trac.web.chrome import add_notice, add_warning |
| 32 | from trac.util.text import exception_to_unicode |
| 33 | |
| 34 | class 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 | |
| 64 | The 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] |